 Documentation
      ¶
      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 Creds ¶
func Creds(c credentials.Credentials) ServerOption
Creds returns a ServerOption that sets credentials for server connections.
func CustomCodec ¶
func CustomCodec(codec Codec) ServerOption
CustomCodec returns a ServerOption that sets a codec for message marshaling and unmarshaling.
func MaxConcurrentStreams ¶
func MaxConcurrentStreams(n uint32) ServerOption
MaxConcurrentStreams returns a ServerOption 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
      ¶
      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. | 
| 
          
            client
            
            command
          
          
         | |
| 
          
            grpc_testing
            
            
          
           Package grpc_testing is a generated protocol buffer package. | Package grpc_testing is a generated protocol buffer package. | 
| 
          
            server
            
            command
          
          
         | |
| 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
            
            command
          
           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
            
            command
          
           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. | 
| Package log defines logging for grpc. | Package log defines logging for grpc. | 
| interop
       | |
| 
          
            client
            
            command
          
          
         | |
| 
          
            grpc_testing
            
            
          
           Package grpc_testing is a generated protocol buffer package. | Package grpc_testing is a generated protocol buffer package. | 
| 
          
            server
            
            command
          
          
         | |
| 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). |