Documentation
¶
Overview ¶
Package rpcは、オブジェクトのエクスポートされたメソッドに、ネットワークやその他のI/O接続を通じてアクセスする機能を提供します。サーバーはオブジェクトを登録し、オブジェクトのタイプ名に基づいてサービスとして表示されるようにします。登録後、オブジェクトのエクスポートされたメソッドはリモートからアクセス可能になります。サーバーは、異なるタイプの複数のオブジェクト（サービス）を登録することができますが、同じタイプの複数のオブジェクトを登録することはエラーです。
以下の条件を満たすメソッドのみがリモートアクセス可能になります。それ以外のメソッドは無視されます：
- メソッドの型がエクスポートされていること。
- メソッドがエクスポートされていること。
- メソッドが2つの引数を持ち、両方の引数がエクスポートされている（または組み込み）型であること。
- メソッドの2番目の引数がポインタであること。
- メソッドが戻り値としてerror型を持つこと。
要するに、メソッドは次のようなスキーマである必要があります。
func (t *T) MethodName(argType T1, replyType *T2) error
ここで、T1とT2はencoding/gobでマーシャリングできる型です。 これらの要件は、異なるコーデックが使用されている場合でも適用されます。 （将来的には、カスタムコーデックに対してこれらの要件は緩和されるかもしれません。）
メソッドの最初の引数は呼び出し元から提供される引数を表し、 2番目の引数は呼び出し元に返される結果パラメータを表します。 メソッドの戻り値がnilでない場合、それはクライアントがerrors.Newによって作成されたかのようにクライアントが確認する文字列として送り返されます。 エラーが返された場合、応答パラメータはクライアントに送り返されません。
サーバーは、ServeConnを呼び出すことによって単一の接続上のリクエストを処理することができます。また、通常はネットワークリスナーを作成し、Acceptを呼び出すか、HTTPリスナーの場合はHandleHTTPとhttp.Serveを呼び出します。
サービスを使用するためには、クライアントは接続を確立し、その後、接続上でNewClientを呼び出します。ダイヤル（DialHTTP）という便利な関数は、生のネットワーク接続（HTTP接続）に対して両方の手順を実行します。結果として得られるClientオブジェクトには、サービスとメソッドを指定するための2つのメソッド、CallとGoがあり、引数を含むポインタと結果パラメータを受け取るポインタを指定します。
Callメソッドは、リモート呼び出しが完了するまで待機し、 Goメソッドは非同期に呼び出しを開始し、Call構造体のDoneチャネルを使用して完了をシグナルします。
明示的なコーデックが設定されていない場合、データの転送には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, err := net.Listen("tcp", ":1234")
if err != nil {
log.Fatal("listen error:", err)
}
go http.Serve(l, nil)
この時点で、クライアントは"Arith"というサービスとそのメソッド"Arith.Multiply"、"Arith.Divide"を見ることができます。呼び出すためには、クライアントはまずサーバーにダイヤルします。
client, err := rpc.DialHTTP("tcp", serverAddress + ":1234")
if err != nil {
log.Fatal("dialing:", err)
}
そして、リモート呼び出しを行うことができます。
// 同期呼び出し
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)
または
// 非同期呼び出し
quotient := new(Quotient)
divCall := client.Go("Arith.Divide", args, quotient, nil)
replyCall := <-divCall.Done // divCallと等しい
// エラーをチェックし、出力などを行います。
サーバーの実装では、クライアントのためのシンプルで型セーフなラッパーを提供することがよくあります。
net/rpcパッケージは凍結されており、新しい機能は受け付けていません。
Index ¶
- Constants
- Variables
- func Accept(lis net.Listener)
- func HandleHTTP()
- func Register(rcvr any) error
- func RegisterName(name string, rcvr any) error
- func ServeCodec(codec ServerCodec)
- func ServeConn(conn io.ReadWriteCloser)
- func ServeRequest(codec ServerCodec) error
- type Call
- type Client
- type ClientCodec
- type Request
- type Response
- type Server
- func (server *Server) Accept(lis net.Listener)
- func (server *Server) HandleHTTP(rpcPath, debugPath string)
- func (server *Server) Register(rcvr any) error
- func (server *Server) RegisterName(name string, rcvr any) 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
Constants ¶
const ( // HandleHTTPで使用されるデフォルト値 DefaultRPCPath = "/_goRPC_" DefaultDebugPath = "/debug/rpc" )
Variables ¶
var DefaultServer = NewServer()
DefaultServerは*Serverのデフォルトインスタンスです。
var ErrShutdown = errors.New("connection is shut down")
Functions ¶
func Accept ¶
Acceptはリスナー上で接続を受け付け、各受信された接続に対してDefaultServerにリクエストを処理します。 Acceptはブロックします。通常、呼び出し元はgo文でそれを呼び出します。
func HandleHTTP ¶
func HandleHTTP()
HandleHTTPはRPCメッセージのためのHTTPハンドラをDefaultServerに登録し、DefaultRPCPathにデバッグハンドラを登録します。 通常はgoステートメントでhttp.Serve()を呼び出す必要があります。
func RegisterName ¶
RegisterNameは、レシーバの具体的な型ではなく、与えられた名前を型として使用します。Registerと同様の動作です。
func ServeCodec ¶
func ServeCodec(codec ServerCodec)
ServeCodecはServeConnと似ていますが、指定されたコーデックを使用して リクエストをデコードし、レスポンスをエンコードします。
func ServeConn ¶
func ServeConn(conn io.ReadWriteCloser)
ServeConnはデフォルトサーバーを単一の接続上で実行します。 ServeConnは、クライアントが切断するまで接続を処理するまでブロックします。 通常、呼び出し元はgo文でServeConnを呼び出します。 ServeConnは、接続上でgobワイヤーフォーマット（パッケージgobを参照）を使用します。 別のコーデックを使用するには、ServeCodecを使用してください。 同時アクセスに関する情報については、NewClientのコメントを参照してください。
func ServeRequest ¶
func ServeRequest(codec ServerCodec) error
ServeRequest は ServeCodec に似ていますが、単一のリクエストを同期的に処理します。 処理が完了してもコーデックを閉じません。
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
ClientはRPCクライアントを表します。 単一のクライアントに関連付けられている複数の保留中の呼び出しがあり、 クライアントは同時に複数のゴルーチンによって使用される場合があります。
func DialHTTPPath ¶
DialHTTPPathは指定したネットワークアドレスとパスでHTTP RPCサーバに接続します。
func NewClient ¶
func NewClient(conn io.ReadWriteCloser) *Client
NewClientは、接続先のサービスセットに対するリクエストを処理するための新しいクライアントを返します。 接続の書き込み側にはバッファが追加されるため、ヘッダとペイロードがまとめて送信されます。
接続の読み込み側と書き込み側はそれぞれ独立してシリアライズされるため、相互ロックは必要ありません。ただし、各半分は同時にアクセスされる可能性があるため、connの実装は同時読み取りや同時書き込みに対して保護する必要があります。
func NewClientWithCodec ¶
func NewClientWithCodec(codec ClientCodec) *Client
NewClientWithCodecは、指定されたコーデックを使用してリクエストをエンコードし、レスポンスをデコードするNewClientと同様です。
func (*Client) Go ¶
Go invokes the function asynchronously. It returns the Call structure representing the invocation. The done channel will signal when the call is complete by returning the same Call object. If done is nil, Go will allocate a new channel. If non-nil, done must be buffered or Go will deliberately crash.
type ClientCodec ¶
type ClientCodec interface {
WriteRequest(*Request, any) error
ReadResponseHeader(*Response) error
ReadResponseBody(any) error
Close() error
}
ClientCodecは、RPCセッションのクライアント側において、RPCリクエストの書き込みとRPCレスポンスの読み取りを実装します。 クライアントはWriteRequestを呼び出して接続にリクエストを書き込み、 ReadResponseHeaderとReadResponseBodyをペアで呼び出してレスポンスを読み込みます。 接続が終了したら、クライアントはCloseを呼び出します。 ReadResponseBodyは、nilの引数で呼び出されることがあり、レスポンスの本文を読み取り、その後破棄するように強制することができます。 同時アクセスに関する情報については、NewClientのコメントを参照してください。
type Response ¶
type Response struct {
ServiceMethod string
Seq uint64
Error string
// contains filtered or unexported fields
}
Responseは、すべてのRPCの戻り値の前に書かれるヘッダです。内部で使用されますが、ネットワークトラフィックを分析する際など、デバッグの支援としてここで文書化されています。
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
ServerはRPCサーバーを表します。
func (*Server) Accept ¶
Acceptはリスナー上で接続を受け入れ、各受信接続のリクエストを処理します。 Acceptはリスナーがnon-nilのエラーを返すまでブロックされます。通常、呼び出し元はgoステートメントでAcceptを呼び出します。
func (*Server) HandleHTTP ¶
HandleHTTPはrpcPathでRPCメッセージのためのHTTPハンドラを登録し、debugPathではデバッグハンドラを登録します。 通常はGoステートメント内でhttp.Serve()を呼び出す必要があります。
func (*Server) Register ¶
Registerは、以下の条件を満たすレシーバーのメソッドのセットをサーバーに公開します：
- エクスポートされた型のエクスポートされたメソッド
- 2つの引数、両方がエクスポートされた型
- 2番目の引数がポインタであること
- エラー型の1つの戻り値
レシーバーがエクスポートされた型でないか、適切なメソッドがない場合は、エラーを返します。また、エラーをパッケージlogを使用してログに記録します。 クライアントは "Type.Method" の形式の文字列を使用して各メソッドにアクセスします。ここで、Typeはレシーバーの具体的な型です。
func (*Server) RegisterName ¶
RegisterNameは、レシーバの具体的な型の代わりに、指定された名前を使用して型を登録します。
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ワイヤフォーマット（package 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 ¶
type ServerCodec interface {
ReadRequestHeader(*Request) error
ReadRequestBody(any) error
WriteResponse(*Response, any) error
// Close can be called multiple times and must be idempotent.
Close() error
}
ServerCodecはRPCセッションのサーバー側でのRPCリクエストの読み取りとRPCレスポンスの書き込みを実装します。 サーバーはReadRequestHeaderとReadRequestBodyをペアで呼び出して接続からリクエストを読み取り、WriteResponseを呼び出してレスポンスを書き込みます。 サーバーは接続が終了したらCloseを呼び出します。ReadRequestBodyはnilの引数で呼び出されることがあり、リクエストの本文を読み取って破棄するためのものです。 同時アクセスに関する情報については、NewClientのコメントを参照してください。
type ServerError ¶
type ServerError string
ServerErrorは、RPC接続のリモート側から返されたエラーを表します。
func (ServerError) Error ¶
func (e ServerError) Error() string
Source Files
Directories