Documentation
¶
Index ¶
- Variables
- func IsShutdownErr(err error) bool
- type Call
- type Codec
- type Conn
- func (conn *Conn) Call(req Request, params, response interface{}) error
- func (conn *Conn) Close() error
- func (conn *Conn) Dead() <-chan struct{}
- func (conn *Conn) Serve(root interface{}, transformErrors func(error) error)
- func (conn *Conn) ServeRoot(root Root, transformErrors func(error) error)
- func (conn *Conn) Start()
- type ErrorCoder
- type Header
- type Killer
- type Observer
- type ObserverFactory
- type ObserverMultiplexer
- type Request
- type RequestError
- type Root
Constants ¶
This section is empty.
Variables ¶
var ErrShutdown = errors.New("connection is shut down")
Functions ¶
func IsShutdownErr ¶
Types ¶
type Codec ¶
type Codec interface {
// ReadHeader reads a message header into hdr.
ReadHeader(hdr *Header) error
// ReadBody reads a message body into the given body value. The
// isRequest parameter specifies whether the message being read
// is a request; if not, it's a response. The body value will
// be a non-nil struct pointer, or nil to signify that the body
// should be read and discarded.
ReadBody(body interface{}, isRequest bool) error
// WriteMessage writes a message with the given header and body.
// The body will always be a struct. It may be called concurrently
// with ReadHeader and ReadBody, but will not be called
// concurrently with itself.
WriteMessage(hdr *Header, body interface{}) error
// Close closes the codec. It may be called concurrently
// and should cause the Read methods to unblock.
Close() error
}
A Codec implements reading and writing of messages in an RPC session. The RPC code calls WriteMessage to write a message to the connection and calls ReadHeader and ReadBody in pairs to read messages.
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
Conn represents an RPC endpoint. It can both initiate and receive RPC requests. There may be multiple outstanding Calls associated with a single Client, and a Client may be used by multiple goroutines simultaneously.
func NewConn ¶
func NewConn(codec Codec, observerFactory ObserverFactory) *Conn
NewConn creates a new connection that uses the given codec for transport, but it does not start it. Conn.Start must be called before any requests are sent or received. If notifier is non-nil, the appropriate method will be called for every RPC request.
func (*Conn) Call ¶
Call invokes the named action on the object of the given type with the given id. The returned values will be stored in response, which should be a pointer. If the action fails remotely, the error will have a cause of type RequestError. The params value may be nil if no parameters are provided; the response value may be nil to indicate that any result should be discarded.
func (*Conn) Close ¶
Close closes the connection and its underlying codec; it returns when all requests have been terminated.
If the connection is serving requests, and the root value implements the Killer interface, its Kill method will be called. The codec will then be closed only when all its outstanding server calls have completed.
Calling Close multiple times is not an error.
func (*Conn) Dead ¶
func (conn *Conn) Dead() <-chan struct{}
Dead returns a channel that is closed when the connection has been closed or the underlying transport has received an error. There may still be outstanding requests. Dead must be called after conn.Start has been called.
func (*Conn) Serve ¶
Serve serves RPC requests on the connection by invoking methods on root. Note that it does not start the connection running, though it may be called once the connection is already started.
The server executes each client request by calling a method on root to obtain an object to act on; then it invokes an method on that object with the request parameters, possibly returning some result.
Methods on the root value are of the form:
M(id string) (O, error)
where M is an exported name, conventionally naming the object type, id is some identifier for the object and O is the type of the returned object.
Methods defined on O may defined in one of the following forms, where T and R must be struct types.
Method() Method() R Method() (R, error) Method() error Method(T) Method(T) R Method(T) (R, error) Method(T) error
If transformErrors is non-nil, it will be called on all returned non-nil errors, for example to transform the errors into ServerErrors with specified codes. There will be a panic if transformErrors returns nil.
Serve may be called at any time on a connection to change the set of methods being served by the connection. This will have no effect on calls that are currently being services. If root is nil, the connection will serve no methods.
func (*Conn) ServeRoot ¶
ServeRoot is like Serve except that it gives the root object dynamic control over what methods are available instead of using reflection on the type.
The server executes each client request by calling FindMethod to obtain a method to invoke. It invokes that method with the request parameters, possibly returning some result.
The Kill method will be called when the connection is closed.
func (*Conn) Start ¶
func (conn *Conn) Start()
Start starts the RPC connection running. It must be called at least once for any RPC connection (client or server side) It has no effect if it has already been called. By default, a connection serves no methods. See Conn.Serve for a description of how to serve methods on a Conn.
type ErrorCoder ¶
type ErrorCoder interface {
ErrorCode() string
}
ErrorCoder represents an any error that has an associated error code. An error code is a short string that represents the kind of an error.
type Header ¶
type Header struct {
// RequestId holds the sequence number of the request.
// For replies, it holds the sequence number of the request
// that is being replied to.
RequestId uint64
// Request holds the action to invoke.
Request Request
// Error holds the error, if any.
Error string
// ErrorCode holds the code of the error, if any.
ErrorCode string
// Version defines the wire format of the request and response structure.
Version int
}
Header is a header written before every RPC call. Since RPC requests can be initiated from either side, the header may represent a request from the other side or a response to an outstanding request.
type Killer ¶
type Killer interface {
Kill()
}
Killer represents a type that can be asked to abort any outstanding requests. The Kill method should return immediately.
type Observer ¶
type Observer interface {
// ServerRequest informs the Observer of a request made
// to the Conn. If the request was not recognized or there was
// an error reading the body, body will be nil.
//
// ServerRequest is called just before the server method
// is invoked.
ServerRequest(hdr *Header, body interface{})
// ServerReply informs the RequestNotifier of a reply sent to a
// server request. The given Request gives details of the call
// that was made; the given Header and body are the header and
// body sent as reply.
//
// ServerReply is called just before the reply is written.
ServerReply(req Request, hdr *Header, body interface{})
}
Observer can be implemented to find out about requests occurring in an RPC conn, for example to print requests for logging purposes. The calls should not block or interact with the Conn object as that can cause delays to the RPC server or deadlock.
type ObserverFactory ¶
type ObserverFactory interface {
// RPCObserver will return a new Observer usually constructed
// from the state previously built up in the Observer. The
// returned instance will be utilized per RPC request.
RPCObserver() Observer
}
ObserverFactory is a type which can construct a new Observer.
type ObserverMultiplexer ¶
type ObserverMultiplexer struct {
// contains filtered or unexported fields
}
ObserverMultiplexer multiplexes calls to an arbitrary number of Observers.
func NewObserverMultiplexer ¶
func NewObserverMultiplexer(rpcObservers ...Observer) *ObserverMultiplexer
NewObserverMultiplexer returns a new ObserverMultiplexer with the provided RequestNotifiers.
func (*ObserverMultiplexer) ServerReply ¶
func (m *ObserverMultiplexer) ServerReply(req Request, hdr *Header, body interface{})
ServerReply implements Observer.
func (*ObserverMultiplexer) ServerRequest ¶
func (m *ObserverMultiplexer) ServerRequest(hdr *Header, body interface{})
ServerRequest implements Observer.
type Request ¶
type Request struct {
// Type holds the type of object to act on.
Type string
// Version holds the version of Type we will be acting on
Version int
// Id holds the id of the object to act on.
Id string
// Action holds the action to perform on the object.
Action string
}
Request represents an RPC to be performed, absent its parameters.
type RequestError ¶
RequestError represents an error returned from an RPC request.
func (*RequestError) Error ¶
func (e *RequestError) Error() string
func (*RequestError) ErrorCode ¶
func (e *RequestError) ErrorCode() string
type Root ¶
type Root interface {
FindMethod(rootName string, version int, methodName string) (rpcreflect.MethodCaller, error)
Killer
}
Root represents a type that can be used to lookup a Method and place calls on that method.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
The jsoncodec package provides a JSON codec for the rpc package.
|
The jsoncodec package provides a JSON codec for the rpc package. |