modulepackage
3.1.0-alpha.1
Repository: https://github.com/capnproto/go-capnproto2.git
Documentation: pkg.go.dev
# README
Cap'n Proto bindings for Go
Cap’n Proto is an insanely fast data interchange format similar to Protocol Buffers, but much faster.
It also includes a sophisticated RPC system based on Object Capabilities, ideal for secure, low-latency applications.
This package provides:
- Go code-generation for Cap'n Proto
- Runtime support for the Go language
- Level 1 support for the Cap'n Proto RPC protocol
Support for Level 3 RPC is planned.
Getting Started
Read the "Getting Started" guide for a high-level introduction to the package API and workflow.
Help and Support
You can find us on Matrix: Go Cap'n Proto
API Reference
Available on pkg.go.dev
API Compatibility
Until the official Cap'n Proto spec is finalized, this repository should be considered beta software.
We use semantic versioning to track compatibility and signal breaking changes. In the spirit of the Go 1 compatibility guarantee, we will make every effort to avoid making breaking API changes within major version numbers, but nevertheless reserve the right to introduce breaking changes for reasons related to:
- Security.
- Changes in the Cap'n Proto specification.
- Bugs.
An exception to this rule is currently in place for the pogs package, which is relatively new and may change over time. However, its functionality has been well-tested, and breaking changes are relatively unlikely.
Note also we may merge breaking changes to the main branch without notice. Users are encouraged to pin their dependencies to a major version, e.g. using the semver-aware features of go get.
License
MIT - see LICENSE file
# Packages
Copyright (c) 2013-2023 Sandstorm Development Group, Inc.
No description provided by the author
Package exc provides an error type for capnp exceptions.
No description provided by the author
Package flowcontrol provides support code for per-object flow control.
Package packed provides functions to read and write the "packed" compression scheme described at https://capnproto.org/encoding.html#packing.
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
No description provided by the author
# Functions
Canonicalize encodes a struct into its canonical form: a single- segment blob without a segment table.
Disconnected returns an error that formats as the given text and will report true when passed to IsDisconnected.
Equal returns true iff p1 and p2 are equal.
ErrorAnswer returns a Answer that always returns error e.
ErrorClient returns a Client that always returns error e.
ImmediateAnswer returns an Answer that accesses ptr.
IsDisconnected reports whether e indicates a failure due to loss of a necessary capability.
IsUnimplemented reports whether e indicates that functionality is unimplemented.
MultiSegment returns a new arena that allocates new segments when they are full.
MustUnmarshalRoot reads an unpacked serialized stream and returns its root pointer.
NewAnswerQueue creates a new answer queue.
NewBitList creates a new bit list, preferring placement in s.
NewClient creates the first reference to a capability.
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.
NewEnumList creates a new list of T, preferring placement in s.
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.
NewLocalPromise returns a client that will eventually resolve to a capability, supplied via the resolver.
NewMessage creates a message with a new root and returns the first segment.
Allocate and return a freshly initialized Metadata.
Analogous to NewSingleSegmentMessage, but using MultiSegment.
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.
NewPointerList allocates a new list of pointers, preferring placement in s.
NewPromise creates a new unresolved promise.
NewPromisedClient creates the first reference to a capability that can resolve to a different capability.
NewReadOnlySingleSegment creates a new read only arena with the given data.
NewRequest creates a new request calling the specified method on the specified client.
NewRootStruct creates a new struct, preferring placement in s, then sets the message's root to the new struct.
NewSingleSegmentMessage(b) is equivalent to NewMessage(SingleSegment(b)), except that it panics instead of returning an error.
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.
SamePtr reports whether p and q refer to the same object.
SetClientLeakFunc sets a callback for reporting Clients that went out of scope without being released.
SingleSegment constructs a SingleSegmentArena from b.
Transform applies a sequence of pipeline operations to a pointer and returns the result.
Unimplemented returns an error that formats as the given text and will report true when passed to IsUnimplemented.
Unmarshal reads an unpacked serialized stream into a message.
UnmarshalPacked reads a packed serialized stream into a message.
# Structs
An Answer is a deferred result of a client call.
AnswerQueue is a queue of method calls to make after an earlier method call finishes.
A Brand is an opaque value used to identify a capability.
CapTable is the indexed list of the clients referenced in the message.
The underlying type of Client.
ClientSnapshot is a snapshot of a client's identity.
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.
A Future accesses a portion of an Answer.
An Interface is a reference to a client in a message's capability table.
The underlying type of List.
A Message is a tree of Cap'n Proto objects, split into one or more segments of contiguous memory.
Metadata is a morally a map[any]any which implements sync.Locker; it is used by the rpc system to attach bookkeeping information to various objects.
A Method identifies a method along with an optional human-readable description of the method.
MultiSegment is an arena that stores object data across multiple []byte buffers, allocating new buffers of exponentially-increasing size when full.
ObjectSize records section sizes for a struct or list.
PipelineClient implements ClientHook by calling to the pipeline's answer.
A PipelineOp describes a step in transforming a pipeline.
A Promise holds the result of an RPC call.
A Ptr is a reference to a Cap'n Proto struct, list, or interface.
No description provided by the author
Recv is the input to ClientHook.Recv.
A Request is a method call to be sent.
A Segment is an allocation arena for Cap'n Proto objects.
Send is the input to ClientHook.Send.
SingleSegmentArena is an Arena implementation that stores message data in a continguous slice.
The underlying type of Struct.
A StructReturner implements Returner by allocating an in-memory message.
A WeakClient is a weak reference to a capability: it refers to a capability without preventing it from being shut down.
# Interfaces
An Arena loads and allocates segments for a Message.
A ClientHook represents a Cap'n Proto capability.
A PipelineCaller implements promise pipelining.
A Resolver supplies a value for a pending promise.
A Returner allocates and sends the results from a received capability method call.
The TypeParam interface must be satisified by a type to be used as a capnproto type parameter.
# Type aliases
A BitList is a reference to a list of booleans.
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.
A list of some Cap'n Proto capability type T.
A Client is a reference to a Cap'n Proto capability.
DataList is an array of pointers to data.
DataOffset is an offset in bytes from the beginning of a struct's data section.
A list of some Cap'n Proto enum type T.
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.
A List is a reference to an array of values.
A PointerList is a reference to an array of pointers.
A ReleaseFunc tells the RPC system that a parameter or result struct is no longer in use and may be reclaimed.
A SegmentID is a numeric identifier for a Segment.
A Size is a size (in bytes).
Struct is a pointer to a struct.
A list of some Cap'n Proto struct type T.
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.