README ¶
#gRPC-Go
The Go implementation of gRPC
Installation
To install this package, you need to install Go 1.4 and setup your Go workspace on your computer. The simplest way to install the library is to run:
$ go get google.golang.org/grpc
Documentation
You can find more detailed documentation and examples in the grpc-common repository.
Status
Alpha - ready for early adopters.
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, ...) (err 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 WithBlock() 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 EnableTracing = true
EnableTracing controls whether to trace RPCs using the golang.org/x/net/trace package. This should only be set before any RPCs are sent or received by this program.
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) (err 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 WithBlock ¶
func WithBlock() DialOption
WithBlock returns a DialOption which makes caller of Dial blocks until the underlying connection is up. Without this, Dial returns immediately and connecting the server happens in background.
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.
Source Files ¶
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. |
Package grpclog defines logging for grpc.
|
Package grpclog defines logging for grpc. |
glogger
Package glogger defines glog-based logging for grpc.
|
Package glogger defines glog-based logging for grpc. |
Package health provides some utility functions to health-check a server.
|
Package health provides some utility functions to health-check a server. |
grpc_health
Package grpc_health is a generated protocol buffer package.
|
Package grpc_health is a generated protocol buffer package. |
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). |