rpc

package
v2.16.0+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 3, 2017 License: MIT Imports: 13 Imported by: 0

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

View Source
var (
	ErrConnClosed = errors.New("rpc: connection closed")
)

Errors

Functions

This section is empty.

Types

type Abort

type Abort Exception

An Abort is a hang-up by a remote vat.

func (Abort) Error

func (a Abort) Error() string

Error returns the exception's reason.

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.

func (*Conn) Bootstrap

func (c *Conn) Bootstrap(ctx context.Context) capnp.Client

Bootstrap returns the receiver's main interface.

func (*Conn) Close

func (c *Conn) Close() error

Close closes the connection and the underlying transport.

func (*Conn) Done

func (c *Conn) Done() <-chan struct{}

Done is a channel that is closed once the connection is fully shut down.

func (*Conn) Err

func (c *Conn) Err() error

Err returns the error that caused the connection to close. Err returns nil before Done is closed.

func (*Conn) Wait

func (c *Conn) Wait() error

Wait waits until the connection is closed or aborted by the remote vat. Wait will always return an error, usually ErrConnClosed or of type Abort.

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 Exception

type Exception struct {
	rpccapnp.Exception
}

An Exception is a Cap'n Proto RPC error.

func (Exception) Error

func (e Exception) Error() string

Error returns the exception's reason.

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.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL