Documentation
¶
Overview ¶
Package rpc implements the Cap'n Proto RPC protocol.
Example ¶
package main
import (
"fmt"
"net"
"golang.org/x/net/context"
"zombiezen.com/go/capnproto2/rpc"
"zombiezen.com/go/capnproto2/rpc/internal/testcapnp"
"zombiezen.com/go/capnproto2/server"
)
func main() {
// Create an in-memory transport. In a real application, you would probably
// use a net.TCPConn (for RPC) or an os.Pipe (for IPC).
p1, p2 := net.Pipe()
t1, t2 := rpc.StreamTransport(p1), rpc.StreamTransport(p2)
// Server-side
srv := testcapnp.Adder_ServerToClient(AdderServer{})
serverConn := rpc.NewConn(t1, rpc.MainInterface(srv.Client))
defer serverConn.Wait()
// Client-side
ctx := context.Background()
clientConn := rpc.NewConn(t2)
defer clientConn.Close()
adderClient := testcapnp.Adder{Client: clientConn.Bootstrap(ctx)}
// Every client call returns a promise. You can make multiple calls
// concurrently.
call1 := adderClient.Add(ctx, func(p testcapnp.Adder_add_Params) error {
p.SetA(5)
p.SetB(2)
return nil
})
call2 := adderClient.Add(ctx, func(p testcapnp.Adder_add_Params) error {
p.SetA(10)
p.SetB(20)
return nil
})
// Calling Struct() on a promise waits until it returns.
result1, err := call1.Struct()
if err != nil {
fmt.Println("Add #1 failed:", err)
return
}
result2, err := call2.Struct()
if err != nil {
fmt.Println("Add #2 failed:", err)
return
}
fmt.Println("Results:", result1.Result(), result2.Result())
}
// An AdderServer is a local implementation of the Adder interface.
type AdderServer struct{}
// Add implements a method
func (AdderServer) Add(call testcapnp.Adder_add) error {
// Acknowledging the call allows other calls to be made (it returns the Answer
// to the caller).
server.Ack(call.Options)
// Parameters are accessed with call.Params.
a := call.Params.A()
b := call.Params.B()
// A result struct is allocated for you at call.Results.
call.Results.SetResult(a + b)
return nil
}
Output: Results: 7 30
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var (
ErrConnClosed = errors.New("rpc: connection closed")
)
Errors
Functions ¶
This section is empty.
Types ¶
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
A Conn is a connection to another Cap'n Proto vat. It is safe to use from multiple goroutines.
func NewConn ¶
func NewConn(t Transport, options ...ConnOption) *Conn
NewConn creates a new connection that communicates on c. Closing the connection will cause c to be closed.
type ConnOption ¶
type ConnOption struct {
// contains filtered or unexported fields
}
A ConnOption is an option for opening a connection.
func BootstrapFunc ¶
func BootstrapFunc(f func(context.Context) (capnp.Client, error)) ConnOption
BootstrapFunc specifies the function to call to create a capability for handling bootstrap messages. This function should not make any RPCs or block.
func ConnLog ¶
func ConnLog(log Logger) ConnOption
ConnLog sets the connection's log to the given Logger, which may be nil to disable logging. By default, logs are sent to the standard log package.
func MainInterface ¶
func MainInterface(client capnp.Client) ConnOption
MainInterface specifies that the connection should use client when receiving bootstrap messages. By default, all bootstrap messages will fail. The client will be closed when the connection is closed.
func SendBufferSize ¶
func SendBufferSize(numMsgs int) ConnOption
SendBufferSize sets the number of outgoing messages to buffer on the connection. This is in addition to whatever buffering the connection's transport performs.
type Logger ¶
type Logger interface {
Infof(ctx context.Context, format string, args ...interface{})
Errorf(ctx context.Context, format string, args ...interface{})
}
A Logger records diagnostic information and errors that are not associated with a call. The arguments passed into a log call are interpreted like fmt.Printf. They should not be held onto past the call's return.
type Transport ¶
type Transport interface {
// SendMessage sends msg.
SendMessage(ctx context.Context, msg rpccapnp.Message) error
// RecvMessage waits to receive a message and returns it.
// Implementations may re-use buffers between calls, so the message is
// only valid until the next call to RecvMessage.
RecvMessage(ctx context.Context) (rpccapnp.Message, error)
// Close releases any resources associated with the transport.
Close() error
}
Transport is the interface that abstracts sending and receiving individual messages of the Cap'n Proto RPC protocol.
func StreamTransport ¶
func StreamTransport(rwc io.ReadWriteCloser) Transport
StreamTransport creates a transport that sends and receives messages by serializing and deserializing unpacked Cap'n Proto messages. Closing the transport will close the underlying ReadWriteCloser.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
logtransport
Package logtransport provides a transport that logs all of its messages.
|
Package logtransport provides a transport that logs all of its messages. |
|
logutil
Package logutil provides functions that can print to a logger.
|
Package logutil provides functions that can print to a logger. |
|
pipetransport
Package pipetransport provides in-memory implementations of rpc.Transport for testing.
|
Package pipetransport provides in-memory implementations of rpc.Transport for testing. |
|
refcount
Package refcount implements a reference-counting client.
|
Package refcount implements a reference-counting client. |