?
This document uses PHP Chinese website manual Release
import "net/rpc"
概況
索引
子目錄
概況
軟件包 rpc 通過網(wǎng)絡(luò)或其他 I/O 連接提供對對象的導(dǎo)出方法的訪問。服務(wù)器注冊一個(gè)對象，使其作為一個(gè)服務(wù)顯示為對象類型的名稱。注冊后，對象的導(dǎo)出方法將可以遠(yuǎn)程訪問。服務(wù)器可以注冊多個(gè)不同類型的對象（服務(wù)），但注冊多個(gè)相同類型的對象是錯(cuò)誤的。
只有符合這些標(biāo)準(zhǔn)的方法才能用于遠(yuǎn)程訪問; 其他方法將被忽略：
- 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.
實(shí)際上，該方法必須看起來像
func (t *T) MethodName(argType T1, replyType *T2) error
T1 和 T2 可以通過 encoding/gob 進(jìn)行編組。即使使用不同的編解碼器，這些要求也適用。（將來，這些要求可能會因?yàn)樽远x編解碼器而變差。）
該方法的第一個(gè)參數(shù)表示由調(diào)用者提供的參數(shù); 第二個(gè)參數(shù)表示要返回給調(diào)用者的結(jié)果參數(shù)。如果非零，方法的返回值作為客戶端看到的字符串傳回，就像由 errors.New 創(chuàng)建的那樣。如果返回錯(cuò)誤，答復(fù)參數(shù)將不會被發(fā)送回客戶端。
服務(wù)器可以通過調(diào)用 ServeConn 來處理單個(gè)連接上的請求。更典型的是，它將創(chuàng)建一個(gè)網(wǎng)絡(luò)監(jiān)聽器并調(diào)用 Accept，或者對于 HTTP 監(jiān)聽器 HandleHTTP 和 http.Serve 。
客戶希望使用該服務(wù)建立連接，然后在連接上調(diào)用 NewClient 。便捷功能 Dial（DialHTTP）執(zhí)行原始網(wǎng)絡(luò)連接（HTTP 連接）的兩個(gè)步驟。生成的 Client 對象具有 Call 和 Go 兩個(gè)方法，它們指定要調(diào)用的服務(wù)和方法，包含參數(shù)的指針以及用于接收結(jié)果參數(shù)的指針。
Call 方法等待遠(yuǎn)程調(diào)用完成，而 Go 方法異步啟動調(diào)用，并使用 Call 結(jié)構(gòu)的完成通道發(fā)送完成信號。
除非設(shè)置了明確的編解碼器，否則使用包 encoding / gob 傳輸數(shù)據(jù)。
這是一個(gè)簡單的例子。服務(wù)器希望導(dǎo)出 Arith 類型的對象：
package serverimport "errors"type Args struct {
A, B int}type Quotient struct {
Quo, Rem int}type Arith intfunc (t *Arith) Multiply(args *Args, reply *int) error {*reply = args.A * args.Breturn 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.Breturn nil}服務(wù)器調(diào)用（對于 HTTP 服務(wù)）：
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)此時(shí)，客戶可以使用“Arith.Multiply”和“Arith.Divide”方法查看“Arith”服務(wù)。要調(diào)用它，客戶端首先撥打服務(wù)器：
client, err := rpc.DialHTTP("tcp", serverAddress + ":1234")if err != nil {
log.Fatal("dialing:", err)}然后它可以進(jìn)行遠(yuǎn)程調(diào)用：
// Synchronous callargs := &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 callquotient := new(Quotient)divCall := client.Go("Arith.Divide", args, quotient, nil)replyCall := <-divCall.Done// will be equal to divCall// check errors, print, etc.服務(wù)器實(shí)現(xiàn)通常會為客戶端提供一個(gè)簡單的，類型安全的包裝器。
net / rpc 軟件包被凍結(jié)，不接受新的功能。
索引
常量
變量
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 的默認(rèn)實(shí)例。
var DefaultServer = NewServer()
var ErrShutdown = errors.New("connection is shut down")func Accept
func Accept(lis net.Listener)
Accept 接受監(jiān)聽器上的連接，并為每個(gè)傳入連接向 DefaultServer 提供請求。接受塊; 調(diào)用者通常在 go 語句中調(diào)用它。
func HandleHTTP
func HandleHTTP()
HandleHTTP 在 DefaultRPCPath 上向 DefaultServer 注冊 RPC 消息的 HTTP 處理程序，并在 DefaultDebugPath 上注冊一個(gè)調(diào)試處理程序。仍然需要調(diào)用 http.Serve（），通常在 go 語句中。
func Register
func Register(rcvr interface{}) errorRegister 在 DefaultServer 中發(fā)布接收者的方法。
func RegisterName
func RegisterName(name string, rcvr interface{}) errorRegisterName 與 Register 類似，但使用提供的名稱來代替接收者的具體類型。
func ServeCodec
func ServeCodec(codec ServerCodec)
ServeCodec 就像 ServeConn，但使用指定的編解碼器來解碼請求并對響應(yīng)進(jìn)行編碼。
func ServeConn
func ServeConn(conn io.ReadWriteCloser)
ServeConn 在一個(gè)連接上運(yùn)行 DefaultServer。ServeConn 塊，服務(wù)于連接，直到客戶端掛斷。調(diào)用者通常在 go 語句中調(diào)用 ServeConn 。ServeConn 在連接上使用 gob wire 格式（請參閱軟件包 gob）。要使用備用編解碼器，請使用 ServeCodec 。
func ServeRequest
func ServeRequest(codec ServerCodec) error
ServeRequest 與 ServeCodec 類似，但同步提供單個(gè)請求。完成后它不會關(guān)閉編解碼器。
type Call
Call 表示一個(gè)活動的 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 代表一個(gè) RPC 客戶端?？赡苡卸鄠€(gè)與一個(gè)客戶端相關(guān)的未決呼叫，并且一個(gè)客戶端可能會被多個(gè) goroutine 同時(shí)使用。
type Client struct { // contains filtered or unexported fields}func Dial
func Dial(network, address string) (*Client, error)
Dial 連接到指定網(wǎng)絡(luò)地址的 RPC 服務(wù)器。
func DialHTTP
func DialHTTP(network, address string) (*Client, error)
DialHTTP 連接到指定網(wǎng)絡(luò)地址的 HTTP RPC 服務(wù)器，該地址監(jiān)聽默認(rèn)的 HTTP RPC 路徑。
func DialHTTPPath
func DialHTTPPath(network, address, path string) (*Client, error)
DialHTTPPath 通過指定的網(wǎng)絡(luò)地址和路徑連接到 HTTP RPC 服務(wù)器。
func NewClient
func NewClient(conn io.ReadWriteCloser) *Client
NewClient 返回一個(gè)新的客戶端來處理對連接另一端的一組服務(wù)的請求。它向連接的寫入端添加一個(gè)緩沖區(qū)，以便將 header 和 payload 作為一個(gè)單元發(fā)送。
func NewClientWithCodec
func NewClientWithCodec(codec ClientCodec) *Client
NewClientWithCodec 與 NewClient 類似，但使用指定的編解碼器對請求進(jìn)行編碼和解碼響應(yīng)。
func (*Client) Call
func (client *Client) Call(serviceMethod string, args interface{}, reply interface{}) errorCall 調(diào)用指定的函數(shù)，等待它完成，并返回其錯(cuò)誤狀態(tài)。
func (*Client) Close
func (client *Client) Close() error
Close 調(diào)用底層編解碼器的 Close 方法。如果連接已關(guān)閉，則返回 ErrShutdown 。
func (*Client) Go
func (client *Client) Go(serviceMethod string, args interface{}, reply interface{}, done chan *Call) *CallGo 異步調(diào)用該函數(shù)。它返回表示調(diào)用的 Call 結(jié)構(gòu)。完成通道將通過返回相同的呼叫對象在呼叫完成時(shí)發(fā)出信號。如果完成，則 Go 將分配一個(gè)新頻道。如果非零，則必須進(jìn)行緩沖或 Go 會故意崩潰。
type ClientCodec
ClientCodec 實(shí)現(xiàn) RPC 請求的寫入和讀取 RPC 會話客戶端的 RPC 響應(yīng)?？蛻舳苏{(diào)用 WriteRequest 向連接寫入請求，并成對調(diào)用 ReadResponseHeader 和 ReadResponseBody 以讀取響應(yīng)?？蛻粼谕瓿蛇B接后調(diào)用 Close 。可以使用零參數(shù)調(diào)用 ReadResponseBody，以強(qiáng)制讀取響應(yīng)主體并丟棄。
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 是每個(gè) RPC 調(diào)用之前寫入的頭文件。它在內(nèi)部使用，但在此處記錄為對調(diào)試的幫助，例如分析網(wǎng)絡(luò)流量時(shí)。
type Request struct {
ServiceMethod string // format: "Service.Method"
Seq uint64 // sequence number chosen by client // contains filtered or unexported fields}type Response
Response 是每個(gè) RPC 返回之前寫入的頭文件。它在內(nèi)部使用，但在此處記錄為對調(diào)試的幫助，例如分析網(wǎng)絡(luò)流量時(shí)。
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 代表一個(gè) RPC 服務(wù)器。
type Server struct { // contains filtered or unexported fields}func NewServer
func NewServer() *Server
NewServer 返回一個(gè)新的服務(wù)器。
func (*Server) Accept
func (server *Server) Accept(lis net.Listener)
Accept 接受偵聽器上的連接并為每個(gè)傳入連接提供請求。接受阻塞，直到偵聽器返回非零錯(cuò)誤。調(diào)用者通常在 go 語句中調(diào)用 Accept 。
func (*Server) HandleHTTP
func (server *Server) HandleHTTP(rpcPath, debugPath string)
HandleHTTP 為 rpcPath 上的 RPC 消息注冊一個(gè) HTTP 處理程序，并在 debugPath 上注冊一個(gè)調(diào)試處理程序。仍然需要調(diào)用 http.Serve（），通常在 go 語句中。
func (*Server) Register
func (server *Server) Register(rcvr interface{}) errorRegister 在服務(wù)器中發(fā)布滿足以下條件的接收器值的方法集合：
- exported method of exported type- two arguments, both of exported type- the second argument is a pointer- one return value, of type error
如果接收方不是導(dǎo)出類型或沒有合適的方法，它將返回一個(gè)錯(cuò)誤。它還使用包日志記錄錯(cuò)誤。客戶端使用“Type.Method”形式的字符串訪問每個(gè)方法，其中 Type 是接收者的具體類型。
func (*Server) RegisterName
func (server *Server) RegisterName(name string, rcvr interface{}) errorRegisterName 與 Register 類似，但使用提供的名稱來代替接收者的具體類型。
func (*Server) ServeCodec
func (server *Server) ServeCodec(codec ServerCodec)
ServeCodec 就像 ServeConn，但使用指定的編解碼器來解碼請求并對響應(yīng)進(jìn)行編碼。
func (*Server) ServeConn
func (server *Server) ServeConn(conn io.ReadWriteCloser)
ServeConn 在單個(gè)連接上運(yùn)行服務(wù)器。ServeConn 塊，服務(wù)于連接，直到客戶端掛斷。調(diào)用者通常在 go 語句中調(diào)用 ServeConn 。ServeConn 在連接上使用 gob wire 格式（請參閱軟件包 gob）。要使用備用編解碼器，請使用 ServeCodec 。
func (*Server) ServeHTTP
func (server *Server) ServeHTTP(w http.ResponseWriter, req *http.Request)
ServeHTTP 實(shí)現(xiàn)了一個(gè)應(yīng)答 RPC 請求的 http.Handler 。
func (*Server) ServeRequest
func (server *Server) ServeRequest(codec ServerCodec) error
ServeRequest 與 ServeCodec 類似，但同步提供單個(gè)請求。完成后它不會關(guān)閉編解碼器。
type ServerCodec
ServerCodec 實(shí)現(xiàn)讀取 RPC 請求并為 RPC 會話的服務(wù)器端寫入 RPC 響應(yīng)。服務(wù)器成對調(diào)用 ReadRequestHeader 和 ReadRequestBody 來讀取來自連接的請求，并且它調(diào)用 WriteResponse 來寫回響應(yīng)。服務(wù)器在連接完成后調(diào)用 Close ?？梢允褂昧銋?shù)調(diào)用 ReadRequestBody 來強(qiáng)制請求的主體被讀取和丟棄。
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 連接的遠(yuǎn)程端返回的錯(cuò)誤。
type ServerError string
func (ServerError) Error
func (e ServerError) Error() string
子目錄
Name | Synopsis |
|---|---|
jsonrpc | 包 jsonrpc 為 rpc 包實(shí)現(xiàn)了一個(gè) JSON-RPC 1.0 ClientCodec 和 ServerCodec |