net/rpc

Package rpc

• import "net/rpc"

• 概况

• 索引

• 子目录

概况

软件包 rpc 通过网络或其他 I/O 连接提供对对象的导出方法的访问。服务器注册一个对象，使其作为一个服务显示为对象类型的名称。注册后，对象的导出方法将可以远程访问。服务器可以注册多个不同类型的对象（服务），但注册多个相同类型的对象是错误的。

只有符合这些标准的方法才能用于远程访问; 其他方法将被忽略：

- the method's type is exported.
- the method is exported.
- the method has two arguments, both exported (or builtin) types.
- the method's second argument is a pointer.
- the method has return type error.

实际上，该方法必须看起来像

func (t *T) MethodName(argType T1, replyType *T2) error

T1 和 T2 可以通过 encoding/gob 进行编组。即使使用不同的编解码器，这些要求也适用。（将来，这些要求可能会因为自定义编解码器而变差。）

该方法的第一个参数表示由调用者提供的参数; 第二个参数表示要返回给调用者的结果参数。该方法的返回值如果非零(nil)，会作为字符串传回，在客户端就像由 errors.New 创建的那样。如果返回错误，答复参数将不会被发送回客户端。

服务器可以通过调用 ServeConn 来处理单个连接上的请求。更典型的是，它将创建一个网络监听器并调用 Accept，或者对于 HTTP 监听器 HandleHTTP 和 http.Serve 。

客户希望使用该服务建立连接，然后在连接上调用 NewClient 。便捷功能 Dial（DialHTTP）执行原始网络连接（HTTP 连接）的两个步骤。生成的 Client 对象具有 Call 和 Go 两个方法，它们指定要调用的服务和方法，包含参数的指针以及用于接收结果参数的指针。

Call 方法等待远程调用完成，而 Go 方法异步启动调用，并使用 Call 结构的完成通道发送完成信号。

除非设置了明确的编解码器，否则使用包 encoding / gob 传输数据。

这是一个简单的例子。服务器希望导出 Arith 类型的对象：

package server

import "errors"

type Args struct {
	A, B int
}

type Quotient struct {
	Quo, Rem int
}

type Arith int

func (t *Arith) Multiply(args *Args, reply *int) error {
	*reply = args.A * args.B
	return nil
}

func (t *Arith) Divide(args *Args, quo *Quotient) error {
	if args.B == 0 {
		return errors.New("divide by zero")
	}
	quo.Quo = args.A / args.B
	quo.Rem = args.A % args.B
	return nil
}

服务器调用（对于 HTTP 服务）：

arith := new(Arith)
rpc.Register(arith)
rpc.HandleHTTP()
l, e := net.Listen("tcp", ":1234")
if e != nil {
	log.Fatal("listen error:", e)
}
go http.Serve(l, nil)

此时，客户可以使用“Arith.Multiply”和“Arith.Divide”方法查看“Arith”服务。要调用它，客户端首先拨打服务器：

client, err := rpc.DialHTTP("tcp", serverAddress + ":1234")
if err != nil {
	log.Fatal("dialing:", err)
}

然后它可以进行远程调用：

// Synchronous call
args := &server.Args{7,8}
var reply int
err = client.Call("Arith.Multiply", args, &reply)
if err != nil {
	log.Fatal("arith error:", err)
}
fmt.Printf("Arith: %d*%d=%d", args.A, args.B, reply)

或

// Asynchronous call
quotient := new(Quotient)
divCall := client.Go("Arith.Divide", args, quotient, nil)
replyCall := <-divCall.Done	// will be equal to divCall
// check errors, print, etc.

服务器实现通常会为客户端提供一个简单的，类型安全的包装器。

net / rpc 软件包被冻结，不接受新的功能。

索引

• 常量

• 变量

• func Accept(lis net.Listener)

• func HandleHTTP()

• func Register(rcvr interface{}) error

• func RegisterName(name string, rcvr interface{}) error

• func ServeCodec(codec ServerCodec)

• func ServeConn(conn io.ReadWriteCloser)

• func ServeRequest(codec ServerCodec) error

• type Call

• type Client

• func Dial(network, address string) (*Client, error)

• func DialHTTP(network, address string) (*Client, error)

• func DialHTTPPath(network, address, path string) (*Client, error)

• func NewClient(conn io.ReadWriteCloser) *Client

• func NewClientWithCodec(codec ClientCodec) *Client

• func (client *Client) Call(serviceMethod string, args interface{}, reply interface{}) error

• func (client *Client) Close() error

• func (client *Client) Go(serviceMethod string, args interface{}, reply interface{}, done chan *Call) *Call

• type ClientCodec

• type Request

• type Response

• type Server

• func NewServer() *Server

• func (server *Server) Accept(lis net.Listener)

• func (server *Server) HandleHTTP(rpcPath, debugPath string)

• func (server *Server) Register(rcvr interface{}) error

• func (server *Server) RegisterName(name string, rcvr interface{}) error

• func (server *Server) ServeCodec(codec ServerCodec)

• func (server *Server) ServeConn(conn io.ReadWriteCloser)

• func (server *Server) ServeHTTP(w http.ResponseWriter, req *http.Request)

• func (server *Server) ServeRequest(codec ServerCodec) error

• type ServerCodec

• type ServerError

• func (e ServerError) Error() string

包文件

client.go debug.go server.go

常量

const (
        // Defaults used by HandleHTTP
        DefaultRPCPath   = "/_goRPC_"
        DefaultDebugPath = "/debug/rpc"
)

变量

DefaultServer 是 * Server 的默认实例。

var DefaultServer = NewServer()

var ErrShutdown = errors.New("connection is shut down")

func Accept（显示源文件）

func Accept(lis net.Listener)

Accept 接受监听器上的连接，并为每个传入连接向 DefaultServer 提供请求。接受块; 调用者通常在 go 语句中调用它。

func HandleHTTP（显示源文件）

func HandleHTTP()

HandleHTTP 在 DefaultRPCPath 上向 DefaultServer 注册 RPC 消息的 HTTP 处理程序，并在 DefaultDebugPath 上注册一个调试处理程序。仍然需要调用 http.Serve（），通常在 go 语句中。

func Register（显示源文件）

func Register(rcvr interface{}) error

Register 在 DefaultServer 中发布接收者的方法。

func RegisterName（显示源文件）

func RegisterName(name string, rcvr interface{}) error

RegisterName 与 Register 类似，但使用提供的名称来代替接收者的具体类型。

func ServeCodec（显示源文件）

func ServeCodec(codec ServerCodec)

ServeCodec 就像 ServeConn，但使用指定的编解码器来解码请求并对响应进行编码。

func ServeConn（显示源文件）

func ServeConn(conn io.ReadWriteCloser)

ServeConn 在一个连接上运行 DefaultServer。ServeConn 块，服务于连接，直到客户端挂断。调用者通常在 go 语句中调用 ServeConn 。ServeConn 在连接上使用 gob wire 格式（请参阅软件包 gob）。要使用备用编解码器，请使用 ServeCodec 。

func ServeRequest（显示源文件）

func ServeRequest(codec ServerCodec) error

ServeRequest 与 ServeCodec 类似，但同步提供单个请求。完成后它不会关闭编解码器。

type Call（显示源文件）

Call 表示一个活动的 RPC 。

type Call struct {
        ServiceMethod string      // The name of the service and method to call.
        Args          interface{} // The argument to the function (*struct).
        Reply         interface{} // The reply from the function (*struct).
        Error         error       // After completion, the error status.
        Done          chan *Call  // Strobes when call is complete.
}

type Client（显示源文件）

Client 代表一个 RPC 客户端。可能有多个与一个客户端相关的未决呼叫，并且一个客户端可能会被多个 goroutine 同时使用。

type Client struct {
        // contains filtered or unexported fields
}

func Dial（显示源文件）

func Dial(network, address string) (*Client, error)

Dial 连接到指定网络地址的 RPC 服务器。

func DialHTTP（显示源文件）

func DialHTTP(network, address string) (*Client, error)

DialHTTP 连接到指定网络地址的 HTTP RPC 服务器，该地址监听默认的 HTTP RPC 路径。

func DialHTTPPath（显示源文件）

func DialHTTPPath(network, address, path string) (*Client, error)

DialHTTPPath 通过指定的网络地址和路径连接到 HTTP RPC 服务器。

func NewClient（显示源文件）

func NewClient(conn io.ReadWriteCloser) *Client

NewClient 返回一个新的客户端来处理对连接另一端的一组服务的请求。它向连接的写入端添加一个缓冲区，以便将 header 和 payload 作为一个单元发送。

func NewClientWithCodec（显示源文件）

func NewClientWithCodec(codec ClientCodec) *Client

NewClientWithCodec 与 NewClient 类似，但使用指定的编解码器对请求进行编码和解码响应。

func (*Client) Call（显示源文件）

func (client *Client) Call(serviceMethod string, args interface{}, reply interface{}) error

Call 调用指定的函数，等待它完成，并返回其错误状态。

func (*Client) Close（显示源文件）

func (client *Client) Close() error

Close 调用底层编解码器的 Close 方法。如果连接已关闭，则返回 ErrShutdown 。

func (*Client) Go（显示源文件）

func (client *Client) Go(serviceMethod string, args interface{}, reply interface{}, done chan *Call) *Call

Go 异步调用该函数。它返回表示调用的 Call 结构。完成通道将通过返回相同的呼叫对象在呼叫完成时发出信号。如果完成，则 Go 将分配一个新频道。如果非零，则必须进行缓冲或 Go 会故意崩溃。

type ClientCodec（显示源文件）

ClientCodec 实现 RPC 请求的写入和读取 RPC 会话客户端的 RPC 响应。客户端调用 WriteRequest 向连接写入请求，并成对调用 ReadResponseHeader 和 ReadResponseBody 以读取响应。客户在完成连接后调用 Close 。可以使用零参数调用 ReadResponseBody，以强制读取响应主体并丢弃。

type ClientCodec interface {
        // WriteRequest must be safe for concurrent use by multiple goroutines.
        WriteRequest(*Request, interface{}) error
        ReadResponseHeader(*Response) error
        ReadResponseBody(interface{}) error

        Close() error
}

type Request（显示源文件）

Request 是每个 RPC 调用之前写入的头文件。它在内部使用，但在此处记录为对调试的帮助，例如分析网络流量时。

type Request struct {
        ServiceMethod string // format: "Service.Method"
        Seq           uint64 // sequence number chosen by client
        // contains filtered or unexported fields
}

type Response（显示源文件）

Response 是每个 RPC 返回之前写入的头文件。它在内部使用，但在此处记录为对调试的帮助，例如分析网络流量时。

type Response struct {
        ServiceMethod string // echoes that of the Request
        Seq           uint64 // echoes that of the request
        Error         string // error, if any.
        // contains filtered or unexported fields
}

type Server（显示源文件）

Server 代表一个 RPC 服务器。

type Server struct {
        // contains filtered or unexported fields
}

func NewServer（显示源文件）

func NewServer() *Server

NewServer 返回一个新的服务器。

func (*Server) Accept（显示源文件）

func (server *Server) Accept(lis net.Listener)

Accept 接受侦听器上的连接并为每个传入连接提供请求。接受阻塞，直到侦听器返回非零错误。调用者通常在 go 语句中调用 Accept 。

func (*Server) HandleHTTP（显示源文件）

func (server *Server) HandleHTTP(rpcPath, debugPath string)

HandleHTTP 为 rpcPath 上的 RPC 消息注册一个 HTTP 处理程序，并在 debugPath 上注册一个调试处理程序。仍然需要调用 http.Serve（），通常在 go 语句中。

func (*Server) Register（显示源文件）

func (server *Server) Register(rcvr interface{}) error

Register 在服务器中发布满足以下条件的接收器值的方法集合：

- exported method of exported type
- two arguments, both of exported type
- the second argument is a pointer
- one return value, of type error

如果接收方不是导出类型或没有合适的方法，它将返回一个错误。它还使用包日志记录错误。客户端使用“Type.Method”形式的字符串访问每个方法，其中 Type 是接收者的具体类型。

func (*Server) RegisterName（显示源文件）

func (server *Server) RegisterName(name string, rcvr interface{}) error

RegisterName 与 Register 类似，但使用提供的名称来代替接收者的具体类型。

func (*Server) ServeCodec（显示源文件）

func (server *Server) ServeCodec(codec ServerCodec)

ServeCodec 就像 ServeConn，但使用指定的编解码器来解码请求并对响应进行编码。

func (*Server) ServeConn（显示源文件）

func (server *Server) ServeConn(conn io.ReadWriteCloser)

ServeConn 在单个连接上运行服务器。ServeConn 块，服务于连接，直到客户端挂断。调用者通常在 go 语句中调用 ServeConn 。ServeConn 在连接上使用 gob wire 格式（请参阅软件包 gob）。要使用备用编解码器，请使用 ServeCodec 。

func (*Server) ServeHTTP（显示源文件）

func (server *Server) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP 实现了一个应答 RPC 请求的 http.Handler 。

func (*Server) ServeRequest（显示源文件）

func (server *Server) ServeRequest(codec ServerCodec) error

ServeRequest 与 ServeCodec 类似，但同步提供单个请求。完成后它不会关闭编解码器。

type ServerCodec（显示源文件）

ServerCodec 实现读取 RPC 请求并为 RPC 会话的服务器端写入 RPC 响应。服务器成对调用 ReadRequestHeader 和 ReadRequestBody 来读取来自连接的请求，并且它调用 WriteResponse 来写回响应。服务器在连接完成后调用 Close 。可以使用零参数调用 ReadRequestBody 来强制请求的主体被读取和丢弃。

type ServerCodec interface {
        ReadRequestHeader(*Request) error
        ReadRequestBody(interface{}) error
        // WriteResponse must be safe for concurrent use by multiple goroutines.
        WriteResponse(*Response, interface{}) error

        Close() error
}

type ServerError（显示源文件）

ServerError 表示从 RPC 连接的远程端返回的错误。

type ServerError string

func (ServerError) Error（显示源文件）

func (e ServerError) Error() string

子目录