...

パッケージ rpc

概要 ▾

rpc パッケージは,ネットワークや他の I/O 接続を越えてオブジェクトのエクスポートメソッドへのアクセスを提供します。
サーバーはオブジェクトを登録し,そのオブジェクトの型名でサービスを公開します。
登録後,エクスポートされたオブジェクトのメソッドは外部からアクセス可能になります。
サーバーは型の異なる複数のオブジェクト (サービス)を登録できますが,
同じ型のオブジェクトを複数登録するとエラーとなります。

これらの基準を満たすメソッドだけがリモートアクセスに使用できるようになります。 他の方法は無視されます。

- メソッドの種類がエクスポートされます。 - メソッドはエクスポートされます。 - メソッドは 2 つの引数を持ち,両方ともエクスポートされた (または組み込みの) 型です。 - メソッドの 2 番目の引数はポインタです。 - メソッドに戻り型エラーがあります。

実際には,このメソッドは概略的に次のようになります

func (t *T) MethodName(引数型 T1, replyType *T2) エラー

T1 と T2 は encoding/gob によって整列化できます。 これらの要件は,異なるコーデックが使用されている場合でも適用されます。 (将来,これらの要件はカスタムコーデックには緩和されるかもしれません。 )

メソッドの最初の引数は,呼び出し元によって渡された引数を表します。 2 番目の引数は,呼び出し元に返される結果パラメータを表します。 メソッドの戻り値が nil 以外の場合は, errors.New によって作成されたものとしてクライアントに認識される文字列として返されます。 エラーが返された場合, reply パラメータはクライアントに返送されません。

サーバーは ServeConn を呼び出すことによって 1 つの接続でリクエストを処理できます。 より一般的には,ネットワークリスナーを作成して Accept を呼び出します。 HTTP リスナーの場合は HandleHTTP および http.Serve を呼び出します。

サービスを使用したいクライアントは,接続を確立してから,その接続に対して NewClient を呼び出します。 便利な機能 Dial (DialHTTP) は,生のネットワーク接続 (HTTP 接続) に対して両方のステップを実行します。 結果の Client オブジェクトには,呼び出すサービスとメソッドを指定する Call と Go という 2 つのメソッド,引数を含むポインタ,および結果パラメータを受け取るポインタがあります。

Call メソッドはリモート呼び出しが完了するのを待ち, Go メソッドは非同期に呼び出しを開始し, Call 構造体の Done チャンネルを使用して完了を通知します。

明示的なコーデックが設定されていない限り,データの転送にパッケージ encoding/gob が使用されます。

これは簡単な例です。 サーバーが Arith 型のオブジェクトをエクスポートしたいとします。

パッケージサーバー

" エラー " をインポート

型 Args 構造体 {A , Bint}

商構造体 {Quo , Remint}

型 Arith int

func (t *Arith) 乗算 (args *Args ,返信 *int) エラー {*reply=args.A*args.Breturnnil}

func (t *Arith) 除算 (args *Args, quo *Quotient) エラー {ifargs.B==0{returnerrors.New("0 で割る ")}quo.Quo=args.A/args.Bquo.Rem=args.A % args.Breturnnil}

サーバー呼び出し (HTTP サービス用):

arith:=new(Arith)rpc.Register(arith)rpc.HandleHTTP()l , e := net.Listen("tcp" , ":1234")e!=nil{log.Fatal("listenerror:" , e)}http.Serve(l , nil) にアクセス

この時点で,クライアントはメソッド "Arith.Multiply" と "Arith.Divide" を持つサービス "Arith" を見ることができます。 起動するには,まずクライアントがサーバーにダイヤルします。

クライアント, err := rpc.DialHTTP("tcp" , serverAddress+":1234")err!=nil{log.Fatal("dialing:" , err)}

それからそれは遠隔電話をかけることができる :

// 同期呼び出し args:= & server.Args{7,8}varreplyinterr=client.Call("Arith.Multiply" , args ,& reply)err!=nil{log.Fatal("aritherror:" , err)}fmt.Printf("Arith: % d* % d= % d" , args.A , args.B ,返信)

または

// 非同期呼び出し quotient:=new(Quotient)divCall:=client.Go("Arith.Divide" , args , quotient , nil)replyCall:=<-divCall.Done//divCall と同じ // エラーをチェックします。 表示など

サーバーの実装は,多くの場合,クライアントに対して単純で型セーフなラッパーを提供します。

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 (
    // 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 は, RPC メッセージの HTTP ハンドラーを DefaultRPCPath 上の DefaultServer に,および DefaultDebugPath 上のデバッグハンドラーに登録します。 通常は go ステートメントで http.Serve() を呼び出す必要があります。

func Register

func Register(rcvr interface{}) error

登録は 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 パッケージを参照) を使用します。 代替コーデックを使用するには, ServeCodec を使用してください。 平行アクセスについては, NewClient のコメントを参照してください。

func ServeRequest

func ServeRequest(codec ServerCodec) error

ServeRequest は ServeCodec に似ていますが, 1 つのリクエストを同期的に処理します。 完了時にコーデックを閉じません。

type Call

呼び出しはアクティブな RPC を表します。

type Call struct {
    ServiceMethod string      // 呼び出すサービスの名前とメソッド。
    Args          interface{} // 関数への引数 (*struct)
    Reply         interface{} // 関数からのレスポンス (*struct)
    Error         error       // 完了後,エラーステータス。
    Done          chan *Call  // 通話が完了するとストロボが鳴ります。
}

type Client

クライアントは RPC クライアントを表します。 1 つのクライアントに関連付けられた複数の未処理の呼び出しがある可能性があり,クライアントは複数のゴルーチンによって平行に使用される可能性があります。

type Client struct {
    // エクスポートされていないフィールドがあります
}

func Dial

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

ダイヤルは,指定されたネットワークアドレスの 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 は,接続のもう一方の端にある一連のサービスへのリクエストを処理するために新しい Client を返します。 ヘッダとペイロードが 1 つの単位として送信されるように,接続の書き込み側にバッファを追加します。

接続の読み取り側と書き込み側は別々にシリアル化されるため,インターロックは必要ありません。 ただし, conn の実装は平行読み取りまたは平行書き込みから保護する必要があるため,各半分に平行にアクセスすることができます。

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 構造体を返します。 done チャンネルは,同じ Call オブジェクトを返すことによって呼び出しが完了したことを知らせます。 done が nil の場合, Go は新しいチャンネルを割り当てます。 nil 以外の場合, done はバッファリングされなければならず,そうでなければ Go は故意にクラッシュします。

type ClientCodec

ClientCodec は, RPC セッションのクライアント側に対して RPC リクエストの書き込みと RPC レスポンスの読み取りを実装します。 クライアントは WriteRequest を呼び出して接続にリクエストを書き込み, ReadResponseHeader と ReadResponseBody をペアで呼び出してレスポンスを読み取ります。 接続が終了すると,クライアントは Close を呼び出します。 ReadResponseBody を nil 引数で呼び出して,レスポンスのボディを強制的に読み取ってから破棄することができます。 平行アクセスについては, NewClient のコメントを参照してください。

type ClientCodec interface {
    WriteRequest(*Request, interface{}) error
    ReadResponseHeader(*Response) error
    ReadResponseBody(interface{}) error

    Close() error
}

type Request

リクエストはすべての RPC 呼び出しの前に書かれたヘッダです。 これは内部的に使用されますが,ネットワークトラフィックを分析する場合など,デバッグの補助としてここで文書化されています。

type Request struct {
    ServiceMethod string // フォーマット : "Service.Method"
    Seq           uint64 // クライアントが選択したシーケンス番号
    // エクスポートされていないフィールドがあります
}

type Response

レスポンスは, RPC が戻るたびに書き込まれるヘッダーです。 これは内部的に使用されますが,ネットワークトラフィックを分析する場合など,デバッグの補助としてここで文書化されています。

type Response struct {
    ServiceMethod string // リクエストのそれを反映する
    Seq           uint64 // リクエストのそれを反映する
    Error         string // もしあれば,エラー。
    // エクスポートされていないフィールドがあります
}

type Server

サーバーは RPC サーバーを表します。

type Server struct {
    // エクスポートされていないフィールドがあります
}

func NewServer

func NewServer() *Server

NewServer は新しいサーバーを返します。

func (*Server) Accept

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

Accept はリスナー上の接続を受け入れ,着信接続ごとにリクエストを処理します。 リスナーが nil 以外のエラーを返すまでブロックを受け入れます。 呼び出し元は通常 go ステートメントで Accept を呼び出します。

func (*Server) HandleHTTP

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

HandleHTTP は, rpcPath に RPC メッセージの HTTP ハンドラを, debugPath にデバッグハンドラを登録します。 通常は go ステートメントで http.Serve() を呼び出す必要があります。

func (*Server) Register

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

登録は,次の条件を満たす受信側値の一連のメソッドをサーバーに公開します。

- エクスポートされた型のエクスポートされたメソッド -2 つの引数,両方ともエクスポートされた型 -2 番目の引数はポインタです -1 つの戻り値, 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 パッケージを参照) を使用します。 代替コーデックを使用するには, ServeCodec を使用してください。 平行アクセスについては, NewClient のコメントを参照してください。

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 に似ていますが, 1 つのリクエストを同期的に処理します。 完了時にコーデックを閉じません。

type ServerCodec

ServerCodec は, RPC セッションのサーバー側に対して RPC リクエストの読み取りと RPC レスポンスの書き込みを実装します。 サーバーは ReadRequestHeader と ReadRequestBody をペアで呼び出して接続からのリクエストを読み取り, WriteResponse を呼び出してレスポンスを書き戻します。 接続が終了すると,サーバーは Close を呼び出します。 ReadRequestBody を nil 引数で呼び出すと,リクエストのボディを強制的に読み取り,破棄することができます。 平行アクセスについては, NewClient のコメントを参照してください。

type ServerCodec interface {
    ReadRequestHeader(*Request) error
    ReadRequestBody(interface{}) error
    WriteResponse(*Response, interface{}) error

    // close は複数回呼び出すことができ,べき等でなければなりません。
    Close() error
}

type ServerError

ServerError は, RPC 接続のリモート側から返されたエラーを表します。

type ServerError string

func (ServerError) Error

func (e ServerError) Error() string

サブディレクトリ

名前 概要
..
jsonrpc jsonrpc パッケージは,rpc パッケージ用に JSON-RPC 1.0 ClientCodec と ServerCodec を実装します。