github.com/shogo82148/std@v1.22.1-0.20240327122250-4e474527810c/net/rpc/client.go (about)

     1  // Copyright 2009 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package rpc
     6  
     7  import (
     8  	"github.com/shogo82148/std/errors"
     9  	"github.com/shogo82148/std/io"
    10  	"github.com/shogo82148/std/sync"
    11  )
    12  
    13  // ServerErrorは、RPC接続のリモート側から返されたエラーを表します。
    14  type ServerError string
    15  
    16  func (e ServerError) Error() string
    17  
    18  var ErrShutdown = errors.New("connection is shut down")
    19  
    20  // CallはアクティブなRPCを表します。
    21  type Call struct {
    22  	ServiceMethod string
    23  	Args          any
    24  	Reply         any
    25  	Error         error
    26  	Done          chan *Call
    27  }
    28  
    29  // ClientはRPCクライアントを表します。
    30  // 単一のクライアントに関連付けられている複数の保留中の呼び出しがあり、
    31  // クライアントは同時に複数のゴルーチンによって使用される場合があります。
    32  type Client struct {
    33  	codec ClientCodec
    34  
    35  	reqMutex sync.Mutex
    36  	request  Request
    37  
    38  	mutex    sync.Mutex
    39  	seq      uint64
    40  	pending  map[uint64]*Call
    41  	closing  bool
    42  	shutdown bool
    43  }
    44  
    45  // ClientCodecは、RPCセッションのクライアント側において、RPCリクエストの書き込みとRPCレスポンスの読み取りを実装します。
    46  // クライアントは [ClientCodec.WriteRequest] を呼び出して接続にリクエストを書き込み、
    47  // [ClientCodec.ReadResponseHeader] と [ClientCodec.ReadResponseBody] をペアで呼び出してレスポンスを読み込みます。
    48  // 接続が終了したら、クライアントは [ClientCodec.Close] を呼び出します。
    49  // ReadResponseBodyは、nilの引数で呼び出されることがあり、レスポンスの本文を読み取り、その後破棄するように強制することができます。
    50  // 同時アクセスに関する情報については、[NewClient] のコメントを参照してください。
    51  type ClientCodec interface {
    52  	WriteRequest(*Request, any) error
    53  	ReadResponseHeader(*Response) error
    54  	ReadResponseBody(any) error
    55  
    56  	Close() error
    57  }
    58  
    59  // NewClientは、接続先のサービスセットに対するリクエストを処理するための新しい [Client] を返します。
    60  // 接続の書き込み側にはバッファが追加されるため、ヘッダとペイロードがまとめて送信されます。
    61  //
    62  // 接続の読み込み側と書き込み側はそれぞれ独立してシリアライズされるため、相互ロックは必要ありません。ただし、各半分は同時にアクセスされる可能性があるため、connの実装は同時読み取りや同時書き込みに対して保護する必要があります。
    63  func NewClient(conn io.ReadWriteCloser) *Client
    64  
    65  // NewClientWithCodecは、指定されたコーデックを使用してリクエストをエンコードし、レスポンスをデコードする [NewClient] と同様です。
    66  func NewClientWithCodec(codec ClientCodec) *Client
    67  
    68  // DialHTTPは、デフォルトのHTTP RPCパスで待ち受けている、指定されたネットワークアドレスのHTTP RPCサーバーに接続します。
    69  func DialHTTP(network, address string) (*Client, error)
    70  
    71  // DialHTTPPathは指定したネットワークアドレスとパスでHTTP RPCサーバに接続します。
    72  func DialHTTPPath(network, address, path string) (*Client, error)
    73  
    74  // Dialは指定されたネットワークアドレスのRPCサーバに接続します。
    75  func Dial(network, address string) (*Client, error)
    76  
    77  // Closeは基礎となるコーデックのCloseメソッドを呼び出します。接続がすでに
    78  // シャットダウン中の場合、[ErrShutdown] が返されます。
    79  func (client *Client) Close() error
    80  
    81  // Go invokes the function asynchronously. It returns the [Call] structure representing
    82  // the invocation. The done channel will signal when the call is complete by returning
    83  // the same Call object. If done is nil, Go will allocate a new channel.
    84  // If non-nil, done must be buffered or Go will deliberately crash.
    85  func (client *Client) Go(serviceMethod string, args any, reply any, done chan *Call) *Call
    86  
    87  // Callは指定された関数を呼び出し、その完了を待ち、エラー状態を返します。
    88  func (client *Client) Call(serviceMethod string, args any, reply any) error