Package Usage: go: capnproto.org/go/capnp/v3
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/capnproto/go-capnproto2/wiki/Getting-Started
capnpc-go provides the compiler backend for 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:
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:
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.
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/capnproto/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.
For the following schema:
capnpc-go will generate:
For each group a typedef is created with a different method set for just the
groups fields:
generates the following:
That way the following may be used to access a field in a group:
Note that group accessors just convert the type and so have no overhead.
Named unions are treated as a group with an inner unnamed union. Unnamed
unions generate an enum Type_Which and a corresponding Which() function:
generates the following:
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:
generates the following:
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:
and in usage:
capnpc-go generates enum values as constants. For example in the capnp file:
In the generated capnp.go file:
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:
In the generated go file:
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:
capnpc-go generates the following Go code (along with the structs
Calculator_evaluate_Params and Calculator_evaluate_Results):
capnpc-go also generates code to implement the interface:
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:
A note about message ordering: by default, only one method per server will
be invoked at a time; when implementing a server method which blocks or takes
a long time, you calling the server.Go function to unblock future calls.
33 versions
Latest release: about 2 years ago
68 dependent packages
View more package details: https://packages.ecosystem.code.gouv.fr/registries/proxy.golang.org/packages/capnproto.org/go/capnp/v3