Documentation ¶
Overview ¶
Package grpc implements an RPC system called gRPC.
See https://github.com/grpc/grpc for more information about gRPC.
Index ¶
- Variables
- func Code(err error) codes.Code
- func Errorf(c codes.Code, format string, a ...interface{}) error
- func Invoke(ctx context.Context, method string, args, reply interface{}, cc *ClientConn, ...) error
- func SendHeader(ctx context.Context, md metadata.MD) error
- func SetTrailer(ctx context.Context, md metadata.MD) error
- type CallOption
- type ClientConn
- type ClientStream
- type Codec
- type DialOption
- func WithCodec(c Codec) DialOption
- func WithDialer(f func(addr string, timeout time.Duration) (net.Conn, error)) DialOption
- func WithPerRPCCredentials(creds credentials.Credentials) DialOption
- func WithTimeout(d time.Duration) DialOption
- func WithTransportCredentials(creds credentials.TransportAuthenticator) DialOption
- type MethodDesc
- type Server
- type ServerOption
- type ServerStream
- type ServiceDesc
- type Stream
- type StreamDesc
Constants ¶
This section is empty.
Variables ¶
var ( // ErrUnspecTarget indicates that the target address is unspecified. ErrUnspecTarget = errors.New("grpc: target is unspecified") // ErrClientConnClosing indicates that the operation is illegal because // the session is closing. ErrClientConnClosing = errors.New("grpc: the client connection is closing") // ErrClientConnTimeout indicates that the connection could not be // established or re-established within the specified timeout. ErrClientConnTimeout = errors.New("grpc: timed out trying to connect") )
var ( // ErrServerStopped indicates that the operation is now illegal because of // the server being stopped. ErrServerStopped = errors.New("grpc: the server has been stopped") )
Functions ¶
func Code ¶
Code returns the error code for err if it was produced by the rpc system. Otherwise, it returns codes.Unknown.
func Errorf ¶
Errorf returns an error containing an error code and a description; Errorf returns nil if c is OK.
func Invoke ¶
func Invoke(ctx context.Context, method string, args, reply interface{}, cc *ClientConn, opts ...CallOption) error
Invoke is called by the generated code. It sends the RPC request on the wire and returns after response is received.
func SendHeader ¶
SendHeader sends header metadata. It may be called at most once from a unary RPC handler. The ctx is the RPC handler's Context or one derived from it.
Types ¶
type CallOption ¶
type CallOption interface {
// contains filtered or unexported methods
}
CallOption configures a Call before it starts or extracts information from a Call after it completes.
func Header ¶
func Header(md *metadata.MD) CallOption
Header returns a CallOptions that retrieves the header metadata for a unary RPC.
func Trailer ¶
func Trailer(md *metadata.MD) CallOption
Trailer returns a CallOptions that retrieves the trailer metadata for a unary RPC.
type ClientConn ¶
type ClientConn struct {
// contains filtered or unexported fields
}
ClientConn represents a client connection to an RPC service.
func Dial ¶
func Dial(target string, opts ...DialOption) (*ClientConn, error)
Dial creates a client connection the given target. TODO(zhaoq): Have an option to make Dial return immediately without waiting for connection to complete.
func (*ClientConn) Close ¶
func (cc *ClientConn) Close() error
Close starts to tear down the ClientConn. Returns ErrClientConnClosing if it has been closed (mostly due to dial time-out). TODO(zhaoq): Make this synchronous to avoid unbounded memory consumption in some edge cases (e.g., the caller opens and closes many ClientConn's in a tight loop.
type ClientStream ¶
type ClientStream interface { // Header returns the header metedata received from the server if there // is any. It blocks if the metadata is not ready to read. Header() (metadata.MD, error) // Trailer returns the trailer metadata from the server. It must be called // after stream.Recv() returns non-nil error (including io.EOF) for // bi-directional streaming and server streaming or stream.CloseAndRecv() // returns for client streaming in order to receive trailer metadata if // present. Otherwise, it could returns an empty MD even though trailer // is present. Trailer() metadata.MD // CloseSend closes the send direction of the stream. It closes the stream // when non-nil error is met. CloseSend() error Stream }
ClientStream defines the interface a client stream has to satify.
func NewClientStream ¶
func NewClientStream(ctx context.Context, desc *StreamDesc, cc *ClientConn, method string, opts ...CallOption) (ClientStream, error)
NewClientStream creates a new Stream for the client side. This is called by generated code.
type Codec ¶
type Codec interface { // Marshal returns the wire format of v. Marshal(v interface{}) ([]byte, error) // Unmarshal parses the wire format into v. Unmarshal(data []byte, v interface{}) error // String returns the name of the Codec implementation. The returned // string will be used as part of content type in transmission. String() string }
Codec defines the interface gRPC uses to encode and decode messages.
type DialOption ¶
type DialOption func(*dialOptions)
DialOption configures how we set up the connection.
func WithCodec ¶
func WithCodec(c Codec) DialOption
WithCodec returns a DialOption which sets a codec for message marshaling and unmarshaling.
func WithDialer ¶
WithDialer returns a DialOption that specifies a function to use for dialing network addresses.
func WithPerRPCCredentials ¶
func WithPerRPCCredentials(creds credentials.Credentials) DialOption
WithPerRPCCredentials returns a DialOption which sets credentials which will place auth state on each outbound RPC.
func WithTimeout ¶
func WithTimeout(d time.Duration) DialOption
WithTimeout returns a DialOption that configures a timeout for dialing a client connection.
func WithTransportCredentials ¶
func WithTransportCredentials(creds credentials.TransportAuthenticator) DialOption
WithTransportCredentials returns a DialOption which configures a connection level security credentials (e.g., TLS/SSL).
type MethodDesc ¶
type MethodDesc struct { MethodName string Handler methodHandler }
MethodDesc represents an RPC service's method specification.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is a gRPC server to serve RPC requests.
func NewServer ¶
func NewServer(opt ...ServerOption) *Server
NewServer creates a gRPC server which has no service registered and has not started to accept requests yet.
func (*Server) RegisterService ¶
func (s *Server) RegisterService(sd *ServiceDesc, ss interface{})
RegisterService register a service and its implementation to the gRPC server. Called from the IDL generated code. This must be called before invoking Serve.
func (*Server) Serve ¶
Serve accepts incoming connections on the listener lis, creating a new ServerTransport and service goroutine for each. The service goroutines read gRPC request and then call the registered handlers to reply to them. Service returns when lis.Accept fails.
func (*Server) Stop ¶
func (s *Server) Stop()
Stop stops the gRPC server. Once Stop returns, the server stops accepting connection requests and closes all the connected connections.
func (*Server) TestingCloseConns ¶
func (s *Server) TestingCloseConns()
TestingCloseConns closes all exiting transports but keeps s.lis accepting new connections. This is for test only now.
type ServerOption ¶
type ServerOption func(*options)
A ServerOption sets options.
func CustomCodec ¶
func CustomCodec(codec Codec) ServerOption
func MaxConcurrentStreams ¶
func MaxConcurrentStreams(n uint32) ServerOption
MaxConcurrentStreams returns an Option that will apply a limit on the number of concurrent streams to each ServerTransport.
type ServerStream ¶
type ServerStream interface { // SendHeader sends the header metadata. It should not be called // after SendProto. It fails if called multiple times or if // called after SendProto. SendHeader(metadata.MD) error // SetTrailer sets the trailer metadata which will be sent with the // RPC status. SetTrailer(metadata.MD) Stream }
ServerStream defines the interface a server stream has to satisfy.
type ServiceDesc ¶
type ServiceDesc struct { ServiceName string // The pointer to the service interface. Used to check whether the user // provided implementation satisfies the interface requirements. HandlerType interface{} Methods []MethodDesc Streams []StreamDesc }
ServiceDesc represents an RPC service's specification.
type Stream ¶
type Stream interface { // Context returns the context for this stream. Context() context.Context // SendMsg blocks until it sends m, the stream is done or the stream // breaks. // On error, it aborts the stream and returns an RPC status on client // side. On server side, it simply returns the error to the caller. // SendMsg is called by generated code. SendMsg(m interface{}) error // RecvMsg blocks until it receives a message or the stream is // done. On client side, it returns io.EOF when the stream is done. On // any other error, it aborts the streama nd returns an RPC status. On // server side, it simply returns the error to the caller. RecvMsg(m interface{}) error }
Stream defines the common interface a client or server stream has to satisfy.
type StreamDesc ¶
type StreamDesc struct { StreamName string Handler streamHandler // At least one of these is true. ServerStreams bool ClientStreams bool }
StreamDesc represents a streaming RPC service's method specification.
Directories ¶
Path | Synopsis |
---|---|
Package benchmark implements the building blocks to setup end-to-end gRPC benchmarks.
|
Package benchmark implements the building blocks to setup end-to-end gRPC benchmarks. |
grpc_testing
Package grpc_testing is a generated protocol buffer package.
|
Package grpc_testing is a generated protocol buffer package. |
Package codes defines the canonical error codes used by gRPC.
|
Package codes defines the canonical error codes used by gRPC. |
Package credentials implements various credentials supported by gRPC library, which encapsulate all the state needed by a client to authenticate with a server and make various assertions, e.g., about the client's identity, role, or whether it is authorized to make a particular call.
|
Package credentials implements various credentials supported by gRPC library, which encapsulate all the state needed by a client to authenticate with a server and make various assertions, e.g., about the client's identity, role, or whether it is authorized to make a particular call. |
examples
|
|
route_guide/client
Package main implements a simple gRPC client that demonstrates how to use gRPC-Go libraries to perform unary, client streaming, server streaming and full duplex RPCs.
|
Package main implements a simple gRPC client that demonstrates how to use gRPC-Go libraries to perform unary, client streaming, server streaming and full duplex RPCs. |
route_guide/proto
Package proto is a generated protocol buffer package.
|
Package proto is a generated protocol buffer package. |
route_guide/server
Package main implements a simple gRPC server that demonstrates how to use gRPC-Go libraries to perform unary, client streaming, server streaming and full duplex RPCs.
|
Package main implements a simple gRPC server that demonstrates how to use gRPC-Go libraries to perform unary, client streaming, server streaming and full duplex RPCs. |
interop
|
|
grpc_testing
Package grpc_testing is a generated protocol buffer package.
|
Package grpc_testing is a generated protocol buffer package. |
Package metadata define the structure of the metadata supported by gRPC library.
|
Package metadata define the structure of the metadata supported by gRPC library. |
test
|
|
codec_perf
Package codec_perf is a generated protocol buffer package.
|
Package codec_perf is a generated protocol buffer package. |
grpc_testing
Package grpc_testing is a generated protocol buffer package.
|
Package grpc_testing is a generated protocol buffer package. |
Package transport defines and implements message oriented communication channel to complete various transactions (e.g., an RPC).
|
Package transport defines and implements message oriented communication channel to complete various transactions (e.g., an RPC). |