modulepackage
2.18.0+incompatible
Repository: https://github.com/jriest/go-capnproto2.git
Documentation: pkg.go.dev
# README
Cap'n Proto bindings for Go
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.
$ go get -u -t zombiezen.com/go/capnproto2/...
$ go test -v zombiezen.com/go/capnproto2/...
This library uses SemVer tags to indicate stable releases. While the goal is that master should always be passing all known tests, tagged releases are vetted more. When possible, use the latest release tag.
$ cd $GOPATH/src/zombiezen.com/go/capnproto2
$ git fetch
$ git checkout v2.16.0 # check the releases page for the latest
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.
The pogs package is relatively new and may change over time.
However, its functionality has been well-tested and will probably only relax restrictions.
Documentation
See the docs on godoc.org.
What is Cap'n Proto?
The best cerealization...
License
MIT - see LICENSE file
# Packages
capnpc-go is the Cap'n proto code generator for Go.
No description provided by the author
Package pogs provides functions to convert Cap'n Proto messages to and
from Go structs.
Package rpc implements the Cap'n Proto RPC protocol.
Package schemas provides a container for Cap'n Proto reflection data.
Package server provides runtime support for implementing Cap'n Proto interfaces locally.
No description provided by the author
# Functions
Canonicalize encodes a struct into its canonical form: a single- segment blob without a segment table.
ErrorAnswer returns a Answer that always returns error e.
ErrorClient returns a Client that always returns error e.
HasData reports whether p has non-zero size.
ImmediateAnswer returns an Answer that accesses s.
IsErrorClient reports whether c was created with ErrorClient.
IsFixedAnswer reports whether an answer was created by ImmediateAnswer or ErrorAnswer.
IsUnimplemented reports whether e indicates an unimplemented method error.
IsValid reports whether p is valid.
MultiSegment returns a new arena that allocates new segments when they are full.
MustUnmarshalRoot reads an unpacked serialized stream and returns its root pointer.
MustUnmarshalRootPtr reads an unpacked serialized stream and returns its root pointer.
NewBitList creates a new bit list, preferring placement in s.
NewCallOptions builds a CallOptions value from a list of individual options.
NewCompositeList creates a new composite list, preferring placement in s.
NewData creates a new list of UInt8 from a byte slice.
NewDataList allocates a new list of data pointers, preferring placement in s.
NewDecoder creates a new Cap'n Proto framer that reads from r.
NewEncoder creates a new Cap'n Proto framer that writes to w.
NewFloat32List creates a new list of Float32, preferring placement in s.
NewFloat64List creates a new list of Float64, preferring placement in s.
NewInt16List creates a new list of Int16, preferring placement in s.
NewInt32List creates a new list of Int32, preferring placement in s.
NewInt64List creates a new list of Int64, preferring placement in s.
NewInt8List creates a new list of Int8, preferring placement in s.
NewInterface creates a new interface pointer.
NewMessage creates a message with a new root and returns the first segment.
NewPackedDecoder creates a new Cap'n Proto framer that reads from a packed stream r.
NewPackedEncoder creates a new Cap'n Proto framer that writes to a packed stream w.
NewPipeline returns a new pipeline based on an answer.
NewPointerList allocates a new list of pointers, preferring placement in s.
NewRootStruct creates a new struct, preferring placement in s, then sets the message's root to the new struct.
NewStruct creates a new struct, preferring placement in s.
NewText creates a new list of UInt8 from a string.
NewTextFromBytes creates a NUL-terminated list of UInt8 from a byte slice.
NewTextList allocates a new list of text pointers, preferring placement in s.
NewUInt16List creates a new list of UInt16, preferring placement in s.
NewUInt32List creates a new list of UInt32, preferring placement in s.
NewUInt64List creates a new list of UInt64, preferring placement in s.
NewUInt8List creates a new list of UInt8, preferring placement in s.
NewVoidList creates a list of voids.
PointerDefault returns p if it is valid, otherwise it unmarshals def.
SamePtr reports whether p and q refer to the same object.
SetOptionValue returns a call option that associates a value to an option key.
SingleSegment returns a new arena with an expanding single-segment buffer.
ToData attempts to convert p into Data.
ToDataDefault attempts to convert p into Data, returning def on failure.
ToInterface converts p to an Interface.
ToList converts p to a List.
ToListDefault attempts to convert p into a list, reading the default value from def if p is not a list.
ToStruct converts p to a Struct.
ToStructDefault attempts to convert p into a struct, reading the default value from def if p is not a struct.
ToText attempts to convert p into Text.
ToTextDefault attempts to convert p into Text, returning def on failure.
Transform applies a sequence of pipeline operations to a pointer and returns the result.
TransformPtr applies a sequence of pipeline operations to a pointer and returns the result.
Unmarshal reads an unpacked serialized stream into a message.
UnmarshalPacked reads a packed serialized stream into a message.
# Variables
ErrNullClient is returned from a call made on a null client pointer.
ErrUnimplemented is the error returned when a method is called on a server that does not implement the method.
# Structs
A BitList is a reference to a list of booleans.
The Call type holds the record for an outgoing interface call.
A CallOption is a function that modifies options on an interface call.
CallOptions holds RPC-specific options for an interface call.
DataList is an array of pointers to data.
A Decoder represents a framer that deserializes a particular Cap'n Proto input stream.
An Encoder represents a framer for serializing a particular Cap'n Proto stream.
Float32List is an array of Float32 values.
Float64List is an array of Float64 values.
Int16List is an array of Int16 values.
Int32List is an array of Int32 values.
Int64List is an array of Int64 values.
Int8List is an array of Int8 values.
An Interface is a reference to a client in a message's capability table.
A List is a reference to an array of values.
A Message is a tree of Cap'n Proto objects, split into one or more segments of contiguous memory.
A Method identifies a method along with an optional human-readable description of the method.
MethodError is an error on an associated method.
ObjectSize records section sizes for a struct or list.
A Pipeline is a generic wrapper for an answer.
A PipelineOp describes a step in transforming a pipeline.
A PointerList is a reference to an array of pointers.
A Ptr is a reference to a Cap'n Proto struct, list, or interface.
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.
A Segment is an allocation arena for Cap'n Proto objects.
Struct is a pointer to a struct.
TextList is an array of pointers to strings.
A UInt16List is an array of UInt16 values.
UInt32List is an array of UInt32 values.
UInt64List is an array of UInt64 values.
A UInt8List is an array of UInt8 values.
A VoidList is a list of zero-sized elements.
# Type aliases
An Address is an index inside a segment's data (in bytes).
BitOffset is an offset in bits from the beginning of a struct's data section.
A CapabilityID is an index into a message's capability table.
DataOffset is an offset in bytes from the beginning of a struct's data section.
PipelineClient implements Client by calling to the pipeline's answer.
A SegmentID is a numeric identifier for a Segment.
A Size is a size (in bytes).