capnp

package module
v2.4.0+incompatible Latest Latest
Warning

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

Go to latest
Published: Apr 6, 2016 License: MIT Imports: 11 Imported by: 0

README

Cap'n Proto bindings for Go

Build Status GoDoc

go-capnproto consists of:

  • a Go code generator for Cap'n Proto
  • a Go package that provides runtime support
  • a Go package that implements Level 1 of the RPC protocol

Getting started

You will need the capnp tool to compile schemas into Go. This package has been tested with Cap'n Proto 0.5.0.

# first: be sure you have your GOPATH env variable setup.
$ go get -u -t zombiezen.com/go/capnproto2/...
$ go test -v zombiezen.com/go/capnproto2/...

Then read the Getting Started guide.

API Compatibility

Consider this package's API as beta software, since the Cap'n Proto spec is not final. In the spirit of the Go 1 compatibility guarantee, I will make every effort to avoid making breaking API changes. The major cases where I reserve the right to make breaking changes are:

  • Security.
  • Changes in the Cap'n Proto specification.
  • Bugs.

Documentation

See the docs on godoc.org.

What is Cap'n Proto?

The best cerealization...

https://capnproto.org/

License

MIT - see LICENSE file

Documentation

Overview

Package capnp is a Cap'n Proto library for Go. https://capnproto.org/

Read the Getting Started guide for a tutorial on how to use this package. https://github.com/zombiezen/go-capnproto2/wiki/Getting-Started

Generating code

capnpc-go provides the compiler backend for capnp.

# First, install capnpc-go to $PATH.
go install zombiezen.com/go/capnproto2/capnpc-go
# Then, generate Go files.
capnp compile -ogo *.capnp

capnpc-go requires two annotations for all files: package and import. package is needed to know what package to place at the head of the generated file and what identifier to use when referring to the type from another package. import should be the fully qualified import path and is used to generate import statement from other packages and to detect when two types are in the same package. For example:

using Go = import "zombiezen.com/go/capnproto2/go.capnp";
$Go.package("main");
$Go.import("zombiezen.com/go/capnproto2/example");

For adding documentation comments to the generated code, there's the doc annotation. This annotation adds the comment to a struct, enum or field so that godoc will pick it up. For example:

struct Zdate $Go.doc("Zdate represents a calendar date") {
  year  @0   :Int16;
  month @1   :UInt8;
  day   @2   :UInt8 ;
}

Messages and Segments

In Cap'n Proto, the unit of communication is a message. A message consists of one or more segments -- contiguous blocks of memory. This allows large messages to be split up and loaded independently or lazily. Typically you will use one segment per message. Logically, a message is organized in a tree of objects, with the root always being a struct (as opposed to a list or primitive). Messages can be read from and written to a stream.

The Message and Segment types are the main types that application code will use from this package. The Message type has methods for marshaling and unmarshaling its segments to the wire format. If the application needs to read or write from a stream, it should use the Encoder and Decoder types.

Pointers

The type for a generic reference to a Cap'n Proto object is Ptr. A Ptr can refer to a struct, a list, or an interface. Ptr, Struct, List, and Interface (the pointer types) have value semantics and refer to data in a single segment. All of the pointer types have a notion of "valid". An invalid pointer will return the default value from any accessor and panic when any setter is called.

In previous versions of this package, the Pointer interface was used instead of the Ptr struct. This interface and functions that use it are now deprecated. See https://github.com/zombiezen/go-capnproto2/wiki/New-Ptr-Type for details about this API change.

Data accessors and setters (i.e. struct primitive fields and list elements) do not return errors, but pointer accessors and setters do. There are a few reasons that a read or write of a pointer can fail, but the most common are bad pointers or allocation failures. For accessors, an invalid object will be returned in case of an error.

Since Go doesn't have generics, wrapper types provide type safety on lists. This package provides lists of basic types, and capnpc-go generates list wrappers for named types. However, if you need to use deeper nesting of lists (e.g. List(List(UInt8))), you will need to use a PointerList and wrap the elements.

Structs

For the following schema:

struct Foo {
  num @0 :UInt32;
  bar @1 :Foo;
}

capnpc-go will generate:

// Foo is a pointer to a Foo struct in a segment.
// Member functions are provided to get/set members in the
// struct.
type Foo struct{ capnp.Struct }

// NewFoo creates a new orphaned Foo struct, preferring placement in
// s.  If there isn't enough space, then another segment in the
// message will be used or allocated.  You can set a field of type Foo
// to this new message, but usually you will want to use the
// NewBar()-style method shown below.
func NewFoo(s *capnp.Segment) (Foo, error)

// NewRootFoo creates a new Foo struct and sets the message's root to
// it.
func NewRootFoo(s *capnp.Segment) (Foo, error)

// ReadRootFoo reads the message's root pointer and converts it to a
// Foo struct.
func ReadRootFoo(msg *capnp.Message) (Foo, error)

// Num returns the value of the num field.
func (s Foo) Num() uint32

// SetNum sets the value of the num field to v.
func (s Foo) SetNum(v uint32)

// Bar returns the value of the bar field.  This can return an error
// if the pointer goes beyond the segment's range, the segment fails
// to load, or the pointer recursion limit has been reached.
func (s Foo) Bar() (Foo, error)

// HasBar reports whether the bar field was initialized (non-null).
func (s Foo) HasBar() bool

// SetBar sets the value of the bar field to v.
func (s Foo) SetBar(v Foo) error

// NewBar sets the bar field to a newly allocated Foo struct,
// preferring placement in s's segment.
func (s Foo) NewBar() (Foo, error)

// Foo_List is a value with pointer semantics. It is created for all
// structs, and is used for List(Foo) in the capnp file.
type Foo_List struct{ capnp.List }

// NewFoo_List creates a new orphaned List(Foo), preferring placement
// in s. This can then be added to a message by using a Set function
// which takes a Foo_List. sz specifies the number of elements in the
// list.  The list's size cannot be changed after creation.
func NewFoo_List(s *capnp.Segment, sz int32) Foo_List

// Len returns the number of elements in the list.
func (s Foo_List) Len() int

// At returns a pointer to the i'th element. If i is an invalid index,
// this will return an invalid Foo (all getters will return default
// values, setters will fail).
func (s Foo_List) At(i int) Foo

// Foo_Promise is a promise for a Foo.  Methods are provided to get
// promises of struct and interface fields.
type Foo_Promise struct{ *capnp.Pipeline }

// Get waits until the promise is resolved and returns the result.
func (p Foo_Promise) Get() (Foo, error)

// Bar returns a promise for that bar field.
func (p Foo_Promise) Bar() Foo_Promise

Groups

For each group a typedef is created with a different method set for just the groups fields:

struct Foo {
	group :Group {
		field @0 :Bool;
	}
}

generates the following:

type Foo struct{ capnp.Struct }
type Foo_group Foo

func (s Foo) Group() Foo_group
func (s Foo_group) Field() bool

That way the following may be used to access a field in a group:

var f Foo
value := f.Group().Field()

Note that group accessors just convert the type and so have no overhead.

Unions

Named unions are treated as a group with an inner unnamed union. Unnamed unions generate an enum Type_Which and a corresponding Which() function:

struct Foo {
	union {
		a @0 :Bool;
		b @1 :Bool;
	}
}

generates the following:

type Foo_Which uint16

const (
	Foo_Which_a Foo_Which = 0
	Foo_Which_b Foo_Which = 1
)

func (s Foo) A() bool
func (s Foo) B() bool
func (s Foo) SetA(v bool)
func (s Foo) SetB(v bool)
func (s Foo) Which() Foo_Which

Which() should be checked before using the getters, and the default case must always be handled.

Setters for single values will set the union discriminator as well as set the value.

For voids in unions, there is a void setter that just sets the discriminator. For example:

struct Foo {
	union {
		a @0 :Void;
		b @1 :Void;
	}
}

generates the following:

func (s Foo) SetA() // Set that we are using A
func (s Foo) SetB() // Set that we are using B

Similarly, for groups in unions, there is a group setter that just sets the discriminator. This must be called before the group getter can be used to set values. For example:

struct Foo {
	union {
		a :group {
			v :Bool
		}
		b :group {
			v :Bool
		}
	}
}

and in usage:

f.SetA()         // Set that we are using group A
f.A().SetV(true) // then we can use the group A getter to set the inner values

Enums

capnpc-go generates enum values as constants. For example in the capnp file:

enum ElementSize {
  empty @0;
  bit @1;
  byte @2;
  twoBytes @3;
  fourBytes @4;
  eightBytes @5;
  pointer @6;
  inlineComposite @7;
}

In the generated capnp.go file:

type ElementSize uint16

const (
	ElementSize_empty           ElementSize = 0
	ElementSize_bit             ElementSize = 1
	ElementSize_byte            ElementSize = 2
	ElementSize_twoBytes        ElementSize = 3
	ElementSize_fourBytes       ElementSize = 4
	ElementSize_eightBytes      ElementSize = 5
	ElementSize_pointer         ElementSize = 6
	ElementSize_inlineComposite ElementSize = 7
)

In addition an enum.String() function is generated that will convert the constants to a string for debugging or logging purposes. By default, the enum name is used as the tag value, but the tags can be customized with a $Go.tag or $Go.notag annotation.

For example:

enum ElementSize {
	empty @0           $Go.tag("void");
	bit @1             $Go.tag("1 bit");
	byte @2            $Go.tag("8 bits");
	inlineComposite @7 $Go.notag;
}

In the generated go file:

func (c ElementSize) String() string {
	switch c {
	case ElementSize_empty:
		return "void"
	case ElementSize_bit:
		return "1 bit"
	case ElementSize_byte:
		return "8 bits"
	default:
		return ""
	}
}

Interfaces

capnpc-go generates type-safe Client wrappers for interfaces. For parameter lists and result lists, structs are generated as described above with the names Interface_method_Params and Interface_method_Results, unless a single struct type is used. For example, for this interface:

interface Calculator {
	evaluate @0 (expression :Expression) -> (value :Value);
}

capnpc-go generates the following Go code (along with the structs Calculator_evaluate_Params and Calculator_evaluate_Results):

// Calculator is a client to a Calculator interface.
type Calculator struct{ Client capnp.Client }

// Evaluate calls `evaluate` on the client.  params is called on a newly
// allocated Calculator_evaluate_Params struct to fill in the parameters.
func (c Calculator) Evaluate(
	ctx context.Context,
	params func(Calculator_evaluate_Params) error,
	opts ...capnp.CallOption) *Calculator_evaluate_Results_Promise

capnpc-go also generates code to implement the interface:

// A Calculator_Server implements the Calculator interface.
type Calculator_Server interface {
	Evaluate(Calculator_evaluate_Call) error
}

// Calculator_evaluate_Call holds the arguments for a Calculator.evaluate server call.
type Calculator_evaluate_Call struct {
	Ctx     context.Context
	Options capnp.CallOptions
	Params  Calculator_evaluate_Params
	Results Calculator_evaluate_Results
}

// Calculator_ServerToClient is equivalent to calling:
// NewCalculator(capnp.NewServer(Calculator_Methods(nil, s), s))
// If s does not implement the Close method, then nil is used.
func Calculator_ServerToClient(s Calculator_Server) Calculator

// Calculator_Methods appends methods from Calculator that call to server and
// returns the methods.  If methods is nil or the capacity of the underlying
// slice is too small, a new slice is returned.
func Calculator_Methods(methods []server.Method, s Calculator_Server) []server.Method

Since a single capability may want to implement many interfaces, you can use multiple *_Methods functions to build a single slice to send to NewServer.

An example of combining the client/server code to communicate with a locally implemented Calculator:

var srv Calculator_Server
calc := Calculator_ServerToClient(srv)
result := calc.Evaluate(ctx, func(params Calculator_evaluate_Params) {
	params.SetExpression(expr)
})
val := result.Value().Get()

A note about message ordering: when implementing a server method, you are responsible for acknowledging delivery of a method call. Failure to do so can cause deadlocks. See the server.Ack function for more details.

Example
// Make a brand new empty message.
msg, seg, err := capnp.NewMessage(capnp.SingleSegment(nil))

// If you want runtime-type identification, this is easily obtained. Just
// wrap everything in a struct that contains a single anoymous union (e.g. struct Z).
// Then always set a Z as the root object in you message/first segment.
// The cost of the extra word of storage is usually worth it, as
// then human readable output is easily obtained via a shell command such as
//
// $ cat binary.cpz | capnp decode aircraft.capnp Z
//
// If you need to conserve space, and know your content in advance, it
// isn't necessary to use an anonymous union. Just supply the type name
// in place of 'Z' in the decode command above.

// There can only be one root.  Subsequent NewRoot* calls will set the root
// pointer and orphan the previous root.
z, err := air.NewRootZ(seg)
if err != nil {
	panic(err)
}

// then non-root objects:
aircraft, err := z.NewAircraft()
if err != nil {
	panic(err)
}
b737, err := aircraft.NewB737()
if err != nil {
	panic(err)
}
planebase, err := b737.NewBase()
if err != nil {
	panic(err)
}

// Set primitive fields
planebase.SetCanFly(true)
planebase.SetName("Henrietta")
planebase.SetRating(100)
planebase.SetMaxSpeed(876) // km/hr
// if we don't set capacity, it will get the default value, in this case 0.
//planebase.SetCapacity(26020) // Liters fuel

// Creating a list
homes, err := air.NewAirport_List(seg, 2)
if err != nil {
	panic(err)
}
homes.Set(0, air.Airport_jfk)
homes.Set(1, air.Airport_lax)
// Setting a list field
planebase.SetHomes(homes)

// Ready to write!

// You can write to memory...
buf, err := msg.Marshal()
if err != nil {
	panic(err)
}
_ = buf

// ... or write to an io.Writer.
file, err := ioutil.TempFile("", "go-capnproto")
if err != nil {
	panic(err)
}
defer file.Close()
defer os.Remove(file.Name())
err = capnp.NewEncoder(file).Encode(msg)
if err != nil {
	panic(err)
}
Output:

Index

Examples

Constants

View Source
const (
	Package    = uint64(0xbea97f1023792be0)
	Import     = uint64(0xe130b601260e44b5)
	Doc        = uint64(0xc58ad6bd519f935e)
	Tag        = uint64(0xa574b41924caefc7)
	Notag      = uint64(0xc8768679ec52e012)
	Customtype = uint64(0xfa10659ae02f2093)
	Name       = uint64(0xc2b96012172f8df1)
)

go.capnp annotation values.

Variables

View Source
var ErrNullClient = errors.New("capnp: call on null client")

ErrNullClient is returned from a call made on a null client pointer.

View Source
var ErrUnimplemented = errors.New("capnp: method not implemented")

ErrUnimplemented is the error returned when a method is called on a server that does not implement the method.

Functions

func HasData

func HasData(p Pointer) bool

HasData is deprecated.

func IsErrorClient

func IsErrorClient(c Client) bool

IsErrorClient reports whether c was created with ErrorClient.

func IsFixedAnswer

func IsFixedAnswer(ans Answer) bool

IsFixedAnswer reports whether an answer was created by ImmediateAnswer or ErrorAnswer.

func IsUnimplemented

func IsUnimplemented(e error) bool

IsUnimplemented reports whether e indicates an unimplemented method error.

func IsValid

func IsValid(p Pointer) bool

IsValid is deprecated in favor of Ptr.IsValid.

func NewMessage

func NewMessage(arena Arena) (msg *Message, first *Segment, err error)

NewMessage creates a message with a new root and returns the first segment. It is an error to call NewMessage on an arena with data in it.

func ToData

func ToData(p Pointer) []byte

ToData is deprecated in favor of Ptr.Data.

func ToDataDefault

func ToDataDefault(p Pointer, def []byte) []byte

ToDataDefault is deprecated in favor of Ptr.DataDefault.

func ToText

func ToText(p Pointer) string

ToText is deprecated in favor of Ptr.Text.

func ToTextDefault

func ToTextDefault(p Pointer, def string) string

ToTextDefault is deprecated in favor of Ptr.TextDefault.

Types

type Address

type Address uint32

An Address is an index inside a segment's data (in bytes).

func (Address) GoString

func (addr Address) GoString() string

GoString returns the address in hex format.

func (Address) String

func (addr Address) String() string

String returns the address in hex format.

type Answer

type Answer interface {
	// Struct waits until the call is finished and returns the result.
	Struct() (Struct, error)

	PipelineCall(transform []PipelineOp, call *Call) Answer
	PipelineClose(transform []PipelineOp) error
}

An Answer is the deferred result of a client call, which is usually wrapped by a Pipeline.

func ErrorAnswer

func ErrorAnswer(e error) Answer

ErrorAnswer returns a Answer that always returns error e.

func ImmediateAnswer

func ImmediateAnswer(s Struct) Answer

ImmediateAnswer returns an Answer that accesses s.

type Arena

type Arena interface {
	// NumSegments returns the number of segments in the arena.
	// This must not be larger than 1<<32.
	NumSegments() int64

	// Data loads the data for the segment with the given ID.
	Data(id SegmentID) ([]byte, error)

	// Allocate allocates a byte slice such that cap(data) - len(data) >= minsz.
	// segs is a map of already loaded segments keyed by ID.  The arena may
	// return an existing segment's ID, in which case the arena is responsible
	// for copying the existing data to the returned byte slice.  Allocate must
	// not modify the segments passed into it.
	Allocate(minsz Size, segs map[SegmentID]*Segment) (SegmentID, []byte, error)
}

An Arena loads and allocates segments for a Message. Segment IDs must be tightly packed in the range [0, NumSegments()).

func MultiSegment

func MultiSegment(b [][]byte) Arena

MultiSegment returns a new arena that allocates new segments when they are full. b can be used to populate the buffer for reading or to reserve memory of a specific size.

func SingleSegment

func SingleSegment(b []byte) Arena

SingleSegment returns a new arena with an expanding single-segment buffer. b can be used to populate the segment for reading or to reserve memory of a specific size. A SingleSegment arena does not return errors unless you attempt to access another segment.

type BitList

type BitList struct{ List }

A BitList is a reference to a list of booleans.

func NewBitList

func NewBitList(s *Segment, n int32) (BitList, error)

NewBitList creates a new bit list, preferring placement in s.

func (BitList) At

func (p BitList) At(i int) bool

At returns the i'th bit.

func (BitList) Set

func (p BitList) Set(i int, v bool)

Set sets the i'th bit to v.

type BitOffset

type BitOffset uint32

BitOffset is an offset in bits from the beginning of a struct's data section.

func (BitOffset) GoString

func (bit BitOffset) GoString() string

GoString returns the offset as a Go expression.

func (BitOffset) String

func (bit BitOffset) String() string

String returns the offset in the format "bit X".

type Call

type Call struct {
	// Ctx is the context of the call.
	Ctx context.Context

	// Method is the interface ID and method ID, along with the optional name,
	// of the method to call.
	Method Method

	// Params is a struct containing parameters for the call.
	// This should be set when the RPC system receives a call for an
	// exported interface.  It is mutually exclusive with ParamsFunc
	// and ParamsSize.
	Params Struct
	// ParamsFunc is a function that populates an allocated struct with
	// the parameters for the call.  ParamsSize determines the size of the
	// struct to allocate.  This is used when application code is using a
	// client.  These settings should be set together; they are mutually
	// exclusive with Params.
	ParamsFunc func(Struct) error
	ParamsSize ObjectSize

	// Options passes RPC-specific options for the call.
	Options CallOptions
}

The Call type holds the record for an outgoing interface call.

func (*Call) Copy

func (call *Call) Copy(s *Segment) (*Call, error)

Copy clones a call, ensuring that its Params are placed. If Call.ParamsFunc is nil, then the same Call will be returned.

func (*Call) PlaceParams

func (call *Call) PlaceParams(s *Segment) (Struct, error)

PlaceParams returns the parameters struct, allocating it inside segment s as necessary. If s is nil, a new single-segment message is allocated.

type CallOption

type CallOption struct {
	// contains filtered or unexported fields
}

A CallOption is a function that modifies options on an interface call.

func SetOptionValue

func SetOptionValue(key, value interface{}) CallOption

SetOptionValue returns a call option that associates a value to an option key. This can be retrieved later with CallOptions.Value.

type CallOptions

type CallOptions struct {
	// contains filtered or unexported fields
}

CallOptions holds RPC-specific options for an interface call. Its usage is similar to the values in context.Context, but is only used for a single call: its values are not intended to propagate to other callees. An example of an option would be the Call.sendResultsTo field in rpc.capnp.

func NewCallOptions

func NewCallOptions(opts []CallOption) CallOptions

NewCallOptions builds a CallOptions value from a list of individual options.

func (CallOptions) Value

func (co CallOptions) Value(key interface{}) interface{}

Value retrieves the value associated with the options for this key, or nil if no value is associated with this key.

func (CallOptions) With

func (co CallOptions) With(opts []CallOption) CallOptions

With creates a copy of the CallOptions value with other options applied.

type CapabilityID

type CapabilityID uint32

A CapabilityID is an index into a message's capability table.

func (CapabilityID) GoString

func (id CapabilityID) GoString() string

GoString returns the ID as a Go expression.

func (CapabilityID) String

func (id CapabilityID) String() string

String returns the ID in the format "capability X".

type Client

type Client interface {
	// Call starts executing a method and returns an answer that will hold
	// the resulting struct.  The call's parameters must be placed before
	// Call() returns.
	//
	// Calls are delivered to the capability in the order they are made.
	// This guarantee is based on the concept of a capability
	// acknowledging delivery of a call: this is specific to an
	// implementation of Client.  A type that implements Client must
	// guarantee that if foo() then bar() is called on a client, that
	// acknowledging foo() happens before acknowledging bar().
	Call(call *Call) Answer

	// Close releases any resources associated with this client.
	// No further calls to the client should be made after calling Close.
	Close() error
}

A Client represents an Cap'n Proto interface type. It is safe to use from multiple goroutines.

Generally, only RPC protocol implementers should provide types that implement Client: call ordering guarantees, promises, and synchronization are tricky to get right. Prefer creating a server that wraps another interface than trying to implement Client.

func ErrorClient

func ErrorClient(e error) Client

ErrorClient returns a Client that always returns error e.

type DataList

type DataList struct{ List }

DataList is an array of pointers to data.

func NewDataList

func NewDataList(s *Segment, n int32) (DataList, error)

NewDataList allocates a new list of data pointers, preferring placement in s.

func (DataList) At

func (l DataList) At(i int) ([]byte, error)

At returns the i'th data in the list.

func (DataList) Set

func (l DataList) Set(i int, v []byte) error

Set sets the i'th data in the list to v.

type DataOffset

type DataOffset uint32

DataOffset is an offset in bytes from the beginning of a struct's data section.

func (DataOffset) GoString

func (off DataOffset) GoString() string

GoString returns the offset as a Go expression.

func (DataOffset) String

func (off DataOffset) String() string

String returns the offset in the format "+X bytes".

type Decoder

type Decoder struct {

	// Maximum number of bytes that can be read per call to Decode.
	// If not set, a reasonable default is used.
	MaxMessageSize uint64
	// contains filtered or unexported fields
}

A Decoder represents a framer that deserializes a particular Cap'n Proto input stream.

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder creates a new Cap'n Proto framer that reads from r.

func NewPackedDecoder

func NewPackedDecoder(r io.Reader) *Decoder

NewPackedDecoder creates a new Cap'n Proto framer that reads from a packed stream r.

func (*Decoder) Decode

func (d *Decoder) Decode() (*Message, error)

Decode reads a message from the decoder stream.

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

An Encoder represents a framer for serializing a particular Cap'n Proto stream.

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

NewEncoder creates a new Cap'n Proto framer that writes to w.

func NewPackedEncoder

func NewPackedEncoder(w io.Writer) *Encoder

NewPackedEncoder creates a new Cap'n Proto framer that writes to a packed stream w.

func (*Encoder) Encode

func (e *Encoder) Encode(m *Message) error

Encode writes a message to the encoder stream.

type Float32List

type Float32List struct{ List }

Float32List is an array of Float32 values.

func NewFloat32List

func NewFloat32List(s *Segment, n int32) (Float32List, error)

NewFloat32List creates a new list of Float32, preferring placement in s.

func (Float32List) At

func (l Float32List) At(i int) float32

At returns the i'th element.

func (Float32List) Set

func (l Float32List) Set(i int, v float32)

Set sets the i'th element to v.

type Float64List

type Float64List struct{ List }

Float64List is an array of Float64 values.

func NewFloat64List

func NewFloat64List(s *Segment, n int32) (Float64List, error)

NewFloat64List creates a new list of Float64, preferring placement in s.

func (Float64List) At

func (l Float64List) At(i int) float64

At returns the i'th element.

func (Float64List) Set

func (l Float64List) Set(i int, v float64)

Set sets the i'th element to v.

type Int16List

type Int16List struct{ List }

Int16List is an array of Int16 values.

func NewInt16List

func NewInt16List(s *Segment, n int32) (Int16List, error)

NewInt16List creates a new list of Int16, preferring placement in s.

func (Int16List) At

func (l Int16List) At(i int) int16

At returns the i'th element.

func (Int16List) Set

func (l Int16List) Set(i int, v int16)

Set sets the i'th element to v.

type Int32List

type Int32List struct{ List }

Int32List is an array of Int32 values.

func NewInt32List

func NewInt32List(s *Segment, n int32) (Int32List, error)

NewInt32List creates a new list of Int32, preferring placement in s.

func (Int32List) At

func (l Int32List) At(i int) int32

At returns the i'th element.

func (Int32List) Set

func (l Int32List) Set(i int, v int32)

Set sets the i'th element to v.

type Int64List

type Int64List struct{ List }

Int64List is an array of Int64 values.

func NewInt64List

func NewInt64List(s *Segment, n int32) (Int64List, error)

NewInt64List creates a new list of Int64, preferring placement in s.

func (Int64List) At

func (l Int64List) At(i int) int64

At returns the i'th element.

func (Int64List) Set

func (l Int64List) Set(i int, v int64)

Set sets the i'th element to v.

type Int8List

type Int8List struct{ List }

Int8List is an array of Int8 values.

func NewInt8List

func NewInt8List(s *Segment, n int32) (Int8List, error)

NewInt8List creates a new list of Int8, preferring placement in s.

func (Int8List) At

func (l Int8List) At(i int) int8

At returns the i'th element.

func (Int8List) Set

func (l Int8List) Set(i int, v int8)

Set sets the i'th element to v.

type Interface

type Interface struct {
	// contains filtered or unexported fields
}

An Interface is a reference to a client in a message's capability table.

func NewInterface

func NewInterface(s *Segment, cap CapabilityID) Interface

NewInterface creates a new interface pointer. No allocation is performed; s is only used for Segment()'s return value.

func ToInterface

func ToInterface(p Pointer) Interface

ToInterface is deprecated in favor of Ptr.Interface.

func (Interface) Capability

func (i Interface) Capability() CapabilityID

Capability returns the capability ID of the interface.

func (Interface) Client

func (i Interface) Client() Client

Client returns the client stored in the message's capability table or nil if the pointer is invalid.

func (Interface) HasData

func (i Interface) HasData() bool

HasData is always true.

func (Interface) IsValid

func (i Interface) IsValid() bool

IsValid returns whether the interface is valid.

func (Interface) Segment

func (i Interface) Segment() *Segment

Segment returns the segment this pointer came from.

func (Interface) ToPtr

func (p Interface) ToPtr() Ptr

ToPtr converts the interface to a generic pointer.

type List

type List struct {
	// contains filtered or unexported fields
}

A List is a reference to an array of values.

func NewCompositeList

func NewCompositeList(s *Segment, sz ObjectSize, n int32) (List, error)

NewCompositeList creates a new composite list, preferring placement in s.

func ToList

func ToList(p Pointer) List

ToList is deprecated in favor of Ptr.List.

func ToListDefault

func ToListDefault(p Pointer, def []byte) (List, error)

ToListDefault is deprecated in favor of Ptr.ListDefault.

func (List) Address

func (p List) Address() Address

Address returns the address the pointer references.

func (List) HasData

func (p List) HasData() bool

HasData reports whether the list's total size is non-zero.

func (List) IsValid

func (p List) IsValid() bool

IsValid returns whether the list is valid.

func (List) Len

func (p List) Len() int

Len returns the length of the list.

func (List) Segment

func (p List) Segment() *Segment

Segment returns the segment this pointer references.

func (List) SetStruct

func (p List) SetStruct(i int, s Struct) error

SetStruct set the i'th element to the value in s.

func (List) Struct

func (p List) Struct(i int) Struct

Struct returns the i'th element as a struct.

func (List) ToPtr

func (p List) ToPtr() Ptr

ToPtr converts the list to a generic pointer.

type Message

type Message struct {
	Arena Arena

	// CapTable is the indexed list of the clients referenced in the
	// message.  Capability pointers inside the message will use this table
	// to map pointers to Clients.  The table is usually populated by the
	// RPC system.
	//
	// See https://capnproto.org/encoding.html#capabilities-interfaces for
	// more details on the capability table.
	CapTable []Client

	// TraverseLimit limits how many total bytes of data are allowed to be
	// traversed while reading.  Traversal is counted when a Struct or
	// List is obtained.  This means that calling a getter for the same
	// sub-struct multiple times will cause it to be double-counted.  Once
	// the traversal limit is reached, pointer accessors will report
	// errors. See https://capnproto.org/encoding.html#amplification-attack
	// for more details on this security measure.
	//
	// If not set, this defaults to 64 MiB.
	TraverseLimit uint64

	// DepthLimit limits how deeply-nested a message structure can be.
	// If not set, this defaults to 64.
	DepthLimit uint
	// contains filtered or unexported fields
}

A Message is a tree of Cap'n Proto objects, split into one or more segments of contiguous memory. The only required field is Arena. A Message is safe to read from multiple goroutines.

func Unmarshal

func Unmarshal(data []byte) (*Message, error)

Unmarshal reads an unpacked serialized stream into a message. No copying is performed, so the objects in the returned message read directly from data.

Example
msg, s, err := capnp.NewMessage(capnp.SingleSegment(nil))
if err != nil {
	fmt.Printf("allocation error %v\n", err)
	return
}
d, err := air.NewRootZdate(s)
if err != nil {
	fmt.Printf("root error %v\n", err)
	return
}
d.SetYear(2004)
d.SetMonth(12)
d.SetDay(7)
data, err := msg.Marshal()
if err != nil {
	fmt.Printf("marshal error %v\n", err)
	return
}

// Read
msg, err = capnp.Unmarshal(data)
if err != nil {
	fmt.Printf("unmarshal error %v\n", err)
	return
}
d, err = air.ReadRootZdate(msg)
if err != nil {
	fmt.Printf("read root error %v\n", err)
	return
}
fmt.Printf("year %d, month %d, day %d\n", d.Year(), d.Month(), d.Day())
Output:

year 2004, month 12, day 7

func (*Message) AddCap

func (m *Message) AddCap(c Client) CapabilityID

AddCap appends a capability to the message's capability table and returns its ID.

func (*Message) Marshal

func (m *Message) Marshal() ([]byte, error)

Marshal concatenates the segments in the message into a single byte slice including framing.

func (*Message) MarshalPacked

func (m *Message) MarshalPacked() ([]byte, error)

MarshalPacked marshals the message in packed form.

func (*Message) NumSegments

func (m *Message) NumSegments() int64

NumSegments returns the number of segments in the message.

func (*Message) ReadLimiter

func (m *Message) ReadLimiter() *ReadLimiter

ReadLimiter returns the message's read limiter. Useful if you want to reset the traversal limit while reading.

func (*Message) Reset

func (m *Message) Reset(arena Arena)

Reset resets a message to use a different arena, allowing a single Message to be reused for reading multiple messages. This invalidates any existing pointers in the Message, so use with caution.

func (*Message) Root

func (m *Message) Root() (Pointer, error)

Root is deprecated in favor of RootPtr.

func (*Message) RootPtr

func (m *Message) RootPtr() (Ptr, error)

RootPtr returns the pointer to the message's root object.

func (*Message) Segment

func (m *Message) Segment(id SegmentID) (*Segment, error)

Segment returns the segment with the given ID.

func (*Message) SetRoot

func (m *Message) SetRoot(p Pointer) error

SetRoot is deprecated in favor of SetRootPtr.

func (*Message) SetRootPtr

func (m *Message) SetRootPtr(p Ptr) error

SetRootPtr sets the message's root object to p.

type Method

type Method struct {
	InterfaceID uint64
	MethodID    uint16

	// Canonical name of the interface.  May be empty.
	InterfaceName string
	// Method name as it appears in the schema.  May be empty.
	MethodName string
}

A Method identifies a method along with an optional human-readable description of the method.

func (*Method) String

func (m *Method) String() string

String returns a formatted string containing the interface name or the method name if present, otherwise it uses the raw IDs. This is suitable for use in error messages and logs.

type MethodError

type MethodError struct {
	Method *Method
	Err    error
}

MethodError is an error on an associated method.

func (*MethodError) Error

func (e *MethodError) Error() string

Error returns the method name concatenated with the error string.

type ObjectSize

type ObjectSize struct {
	DataSize     Size
	PointerCount uint16
}

ObjectSize records section sizes for a struct or list.

func (ObjectSize) GoString

func (sz ObjectSize) GoString() string

GoString formats the ObjectSize as a keyed struct literal.

func (ObjectSize) String

func (sz ObjectSize) String() string

String returns a short, human readable representation of the object size.

type Pipeline

type Pipeline struct {
	// contains filtered or unexported fields
}

A Pipeline is a generic wrapper for an answer.

func NewPipeline

func NewPipeline(ans Answer) *Pipeline

NewPipeline returns a new pipeline based on an answer.

func (*Pipeline) Answer

func (p *Pipeline) Answer() Answer

Answer returns the answer the pipeline is derived from.

func (*Pipeline) Client

func (p *Pipeline) Client() *PipelineClient

Client returns the client version of p.

func (*Pipeline) GetPipeline

func (p *Pipeline) GetPipeline(off uint16) *Pipeline

GetPipeline returns a derived pipeline which yields the pointer field given.

func (*Pipeline) GetPipelineDefault

func (p *Pipeline) GetPipelineDefault(off uint16, def []byte) *Pipeline

GetPipelineDefault returns a derived pipeline which yields the pointer field given, defaulting to the value given.

func (*Pipeline) Struct

func (p *Pipeline) Struct() (Struct, error)

Struct waits until the answer is resolved and returns the struct this pipeline represents.

func (*Pipeline) Transform

func (p *Pipeline) Transform() []PipelineOp

Transform returns the operations needed to transform the root answer into the value p represents.

type PipelineClient

type PipelineClient Pipeline

PipelineClient implements Client by calling to the pipeline's answer.

func (*PipelineClient) Call

func (pc *PipelineClient) Call(call *Call) Answer

Call calls Answer.PipelineCall with the pipeline's transform.

func (*PipelineClient) Close

func (pc *PipelineClient) Close() error

Close calls Answer.PipelineClose with the pipeline's transform.

type PipelineOp

type PipelineOp struct {
	Field        uint16
	DefaultValue []byte
}

A PipelineOp describes a step in transforming a pipeline. It maps closely with the PromisedAnswer.Op struct in rpc.capnp.

func (PipelineOp) String

func (op PipelineOp) String() string

String returns a human-readable description of op.

type Pointer

type Pointer interface {
	// Segment returns the segment this pointer points into.
	// If nil, then this is an invalid pointer.
	Segment() *Segment

	// HasData reports whether the object referenced by the pointer has
	// non-zero size.
	HasData() bool
	// contains filtered or unexported methods
}

Pointer is deprecated in favor of Ptr.

func MustUnmarshalRoot

func MustUnmarshalRoot(data []byte) Pointer

MustUnmarshalRoot is deprecated in favor of MustUnmarshalRootPtr.

func PointerDefault

func PointerDefault(p Pointer, def []byte) (Pointer, error)

PointerDefault is deprecated in favor of Ptr.Default.

func Transform

func Transform(p Pointer, transform []PipelineOp) (Pointer, error)

Transform is deprecated in favor of TransformPtr.

type PointerList

type PointerList struct{ List }

A PointerList is a reference to an array of pointers.

func NewPointerList

func NewPointerList(s *Segment, n int32) (PointerList, error)

NewPointerList allocates a new list of pointers, preferring placement in s.

func (PointerList) At

func (p PointerList) At(i int) (Pointer, error)

At is deprecated in favor of PtrAt.

func (PointerList) PtrAt

func (p PointerList) PtrAt(i int) (Ptr, error)

PtrAt returns the i'th pointer in the list.

func (PointerList) Set

func (p PointerList) Set(i int, v Pointer) error

Set is deprecated in favor of SetPtr.

func (PointerList) SetPtr

func (p PointerList) SetPtr(i int, v Ptr) error

SetPtr sets the i'th pointer in the list to v.

type Ptr

type Ptr struct {
	// contains filtered or unexported fields
}

A Ptr is a reference to a Cap'n Proto struct, list, or interface.

func MustUnmarshalRootPtr

func MustUnmarshalRootPtr(data []byte) Ptr

MustUnmarshalRootPtr reads an unpacked serialized stream and returns its root pointer. If there is any error, it panics.

func TransformPtr

func TransformPtr(p Ptr, transform []PipelineOp) (Ptr, error)

TransformPtr applies a sequence of pipeline operations to a pointer and returns the result.

func (Ptr) Data

func (p Ptr) Data() []byte

Data attempts to convert p into Data, returning nil if p is not a valid 1-byte list pointer.

func (Ptr) DataDefault

func (p Ptr) DataDefault(def []byte) []byte

DataDefault attempts to convert p into Data, returning def if p is not a valid 1-byte list pointer.

func (Ptr) Default

func (p Ptr) Default(def []byte) (Ptr, error)

Default returns p if it is valid, otherwise it unmarshals def.

func (Ptr) Interface

func (p Ptr) Interface() Interface

Interface converts p to an Interface. If p does not hold a List pointer, the zero value is returned.

func (Ptr) IsValid

func (p Ptr) IsValid() bool

IsValid reports whether p is valid.

func (Ptr) List

func (p Ptr) List() List

List converts p to a List. If p does not hold a List pointer, the zero value is returned.

func (Ptr) ListDefault

func (p Ptr) ListDefault(def []byte) (List, error)

ListDefault attempts to convert p into a list, reading the default value from def if p is not a list.

func (Ptr) Segment

func (p Ptr) Segment() *Segment

Segment returns the segment this pointer points into. If nil, then this is an invalid pointer.

func (Ptr) Struct

func (p Ptr) Struct() Struct

Struct converts p to a Struct. If p does not hold a Struct pointer, the zero value is returned.

func (Ptr) StructDefault

func (p Ptr) StructDefault(def []byte) (Struct, error)

StructDefault attempts to convert p into a struct, reading the default value from def if p is not a struct.

func (Ptr) Text

func (p Ptr) Text() string

Text attempts to convert p into Text, returning an empty string if p is not a valid 1-byte list pointer.

func (Ptr) TextDefault

func (p Ptr) TextDefault(def string) string

TextDefault attempts to convert p into Text, returning def if p is not a valid 1-byte list pointer.

type ReadLimiter

type ReadLimiter struct {
	// contains filtered or unexported fields
}

A ReadLimiter tracks the number of bytes read from a message in order to avoid amplification attacks as detailed in https://capnproto.org/encoding.html#amplification-attack. It is safe to use from multiple goroutines.

func (*ReadLimiter) Reset

func (rl *ReadLimiter) Reset(limit uint64)

Reset sets the number of bytes allowed to be read.

func (*ReadLimiter) Unread

func (rl *ReadLimiter) Unread(sz Size)

Unread increases the limit by sz.

type Segment

type Segment struct {
	// contains filtered or unexported fields
}

A Segment is an allocation arena for Cap'n Proto objects. It is part of a Message, which can contain other segments that reference each other.

func (*Segment) Data

func (s *Segment) Data() []byte

Data returns the raw byte slice for the segment.

func (*Segment) ID

func (s *Segment) ID() SegmentID

ID returns the segment's ID.

func (*Segment) Message

func (s *Segment) Message() *Message

Message returns the message that contains s.

type SegmentID

type SegmentID uint32

A SegmentID is a numeric identifier for a Segment.

type Size

type Size uint32

A Size is a size (in bytes).

func (Size) GoString

func (sz Size) GoString() string

GoString returns the size as a Go expression.

func (Size) String

func (sz Size) String() string

String returns the size in the format "X bytes".

type Struct

type Struct struct {
	// contains filtered or unexported fields
}

Struct is a pointer to a struct.

func NewRootStruct

func NewRootStruct(s *Segment, sz ObjectSize) (Struct, error)

NewRootStruct creates a new struct, preferring placement in s, then sets the message's root to the new struct.

func NewStruct

func NewStruct(s *Segment, sz ObjectSize) (Struct, error)

NewStruct creates a new struct, preferring placement in s.

func ToStruct

func ToStruct(p Pointer) Struct

ToStruct is deprecated in favor of Ptr.Struct.

func ToStructDefault

func ToStructDefault(p Pointer, def []byte) (Struct, error)

ToStructDefault is deprecated in favor of Ptr.StructDefault.

func (Struct) Address

func (p Struct) Address() Address

Address returns the address the pointer references.

func (Struct) Bit

func (p Struct) Bit(n BitOffset) bool

Bit returns the bit that is n bits from the start of the struct.

func (Struct) HasData

func (p Struct) HasData() bool

HasData reports whether the struct has a non-zero size.

func (Struct) IsValid

func (p Struct) IsValid() bool

IsValid returns whether the struct is valid.

func (Struct) Pointer

func (p Struct) Pointer(i uint16) (Pointer, error)

Pointer is deprecated in favor of Ptr.

func (Struct) Ptr

func (p Struct) Ptr(i uint16) (Ptr, error)

Ptr returns the i'th pointer in the struct.

func (Struct) Segment

func (p Struct) Segment() *Segment

Segment returns the segment this pointer came from.

func (Struct) SetBit

func (p Struct) SetBit(n BitOffset, v bool)

SetBit sets the bit that is n bits from the start of the struct to v.

func (Struct) SetPointer

func (p Struct) SetPointer(i uint16, src Pointer) error

SetPointer is deprecated in favor of SetPtr.

func (Struct) SetPtr

func (p Struct) SetPtr(i uint16, src Ptr) error

SetPtr sets the i'th pointer in the struct to src.

func (Struct) SetUint16

func (p Struct) SetUint16(off DataOffset, v uint16)

SetUint16 sets the 16-bit integer that is off bytes from the start of the struct to v.

func (Struct) SetUint32

func (p Struct) SetUint32(off DataOffset, v uint32)

SetUint32 sets the 32-bit integer that is off bytes from the start of the struct to v.

func (Struct) SetUint64

func (p Struct) SetUint64(off DataOffset, v uint64)

SetUint64 sets the 64-bit integer that is off bytes from the start of the struct to v.

func (Struct) SetUint8

func (p Struct) SetUint8(off DataOffset, v uint8)

SetUint8 sets the 8-bit integer that is off bytes from the start of the struct to v.

func (Struct) ToPtr

func (p Struct) ToPtr() Ptr

ToPtr converts the struct to a generic pointer.

func (Struct) Uint16

func (p Struct) Uint16(off DataOffset) uint16

Uint16 returns a 16-bit integer from the struct's data section.

func (Struct) Uint32

func (p Struct) Uint32(off DataOffset) uint32

Uint32 returns a 32-bit integer from the struct's data section.

func (Struct) Uint64

func (p Struct) Uint64(off DataOffset) uint64

Uint64 returns a 64-bit integer from the struct's data section.

func (Struct) Uint8

func (p Struct) Uint8(off DataOffset) uint8

Uint8 returns an 8-bit integer from the struct's data section.

type TextList

type TextList struct{ List }

TextList is an array of pointers to strings.

func NewTextList

func NewTextList(s *Segment, n int32) (TextList, error)

NewTextList allocates a new list of text pointers, preferring placement in s.

func (TextList) At

func (l TextList) At(i int) (string, error)

At returns the i'th string in the list.

func (TextList) BytesAt

func (l TextList) BytesAt(i int) ([]byte, error)

BytesAt returns the i'th element in the list as a byte slice. The underlying array of the slice is the segment data.

func (TextList) Set

func (l TextList) Set(i int, v string) error

Set sets the i'th string in the list to v.

type UInt16List

type UInt16List struct{ List }

A UInt16List is an array of UInt16 values.

func NewUInt16List

func NewUInt16List(s *Segment, n int32) (UInt16List, error)

NewUInt16List creates a new list of UInt16, preferring placement in s.

func (UInt16List) At

func (l UInt16List) At(i int) uint16

At returns the i'th element.

func (UInt16List) Set

func (l UInt16List) Set(i int, v uint16)

Set sets the i'th element to v.

type UInt32List

type UInt32List struct{ List }

UInt32List is an array of UInt32 values.

func NewUInt32List

func NewUInt32List(s *Segment, n int32) (UInt32List, error)

NewUInt32List creates a new list of UInt32, preferring placement in s.

func (UInt32List) At

func (l UInt32List) At(i int) uint32

At returns the i'th element.

func (UInt32List) Set

func (l UInt32List) Set(i int, v uint32)

Set sets the i'th element to v.

type UInt64List

type UInt64List struct{ List }

UInt64List is an array of UInt64 values.

func NewUInt64List

func NewUInt64List(s *Segment, n int32) (UInt64List, error)

NewUInt64List creates a new list of UInt64, preferring placement in s.

func (UInt64List) At

func (l UInt64List) At(i int) uint64

At returns the i'th element.

func (UInt64List) Set

func (l UInt64List) Set(i int, v uint64)

Set sets the i'th element to v.

type UInt8List

type UInt8List struct{ List }

A UInt8List is an array of UInt8 values.

func NewData

func NewData(s *Segment, v []byte) (UInt8List, error)

NewData creates a new list of UInt8 from a byte slice.

func NewText

func NewText(s *Segment, v string) (UInt8List, error)

NewText creates a new list of UInt8 from a string.

func NewUInt8List

func NewUInt8List(s *Segment, n int32) (UInt8List, error)

NewUInt8List creates a new list of UInt8, preferring placement in s.

func (UInt8List) At

func (l UInt8List) At(i int) uint8

At returns the i'th element.

func (UInt8List) Set

func (l UInt8List) Set(i int, v uint8)

Set sets the i'th element to v.

type VoidList

type VoidList struct{ List }

A VoidList is a list of zero-sized elements.

func NewVoidList

func NewVoidList(s *Segment, n int32) VoidList

NewVoidList creates a list of voids. No allocation is performed; s is only used for Segment()'s return value.

Directories

Path Synopsis
capnpc-go is the Cap'n proto code generator for Go.
capnpc-go is the Cap'n proto code generator for Go.
internal
demo
Package demo contains example tests.
Package demo contains example tests.
fulfiller
Package fulfiller provides a type that implements capnp.Answer that resolves by calling setter methods.
Package fulfiller provides a type that implements capnp.Answer that resolves by calling setter methods.
packed
Package packed provides functions to read and write the "packed" compression scheme described at https://capnproto.org/encoding.html#packing.
Package packed provides functions to read and write the "packed" compression scheme described at https://capnproto.org/encoding.html#packing.
queue
Package queue implements a generic queue using a ring buffer.
Package queue implements a generic queue using a ring buffer.
rpc
Package rpc implements the Cap'n Proto RPC protocol.
Package rpc implements the Cap'n Proto RPC protocol.
internal/logtransport
Package logtransport provides a transport that logs all of its messages.
Package logtransport provides a transport that logs all of its messages.
internal/logutil
Package logutil provides functions that can print to a logger.
Package logutil provides functions that can print to a logger.
internal/pipetransport
Package pipetransport provides in-memory implementations of rpc.Transport for testing.
Package pipetransport provides in-memory implementations of rpc.Transport for testing.
internal/refcount
Package refcount implements a reference-counting client.
Package refcount implements a reference-counting client.
Package server provides runtime support for implementing Cap'n Proto interfaces locally.
Package server provides runtime support for implementing Cap'n Proto interfaces locally.

Jump to

Keyboard shortcuts

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