Crate capnp 

Cap’n Proto Runtime Library

This crate contains basic facilities for reading and writing Cap’n Proto messages in Rust. It is intended to be used in conjunction with code generated by the capnpc-rust crate.

type newtypes

A schema type declaration is a newtype. A scalar newtype (type Uuid = Data) generates a module of transparent Reader/Builder/Owned aliases – wire-identical to the underlying type, preserving only the name. An inline group or union newtype (type Vec3 = group { x @0 :Float32; ... }, stamped into a struct at explicit @[...] ordinals so it shares the parent’s space with no pointer indirection) generates a module containing:

• Reader / Builder traits – the newtype’s shared interface. Each use site is a distinct concrete type (with its offsets baked in), and all of them implement these traits, so an impl vec3::Reader / impl vec3::Builder bound lets you write code generic over every use site. A union newtype’s Reader additionally has which(), returning a shared Which enum.
• AnyReader / AnyBuilder – a single erased type spanning use sites, reading field offsets from a runtime table (built with a concrete accessor’s as_any()). Use them where one type must span use sites – a Vec, a return type, a struct field. A per-use-site concrete type can’t do that, and neither can &dyn once the newtype nests another newtype or is a union (those need associated types, which are not object-safe). The erased carriers mirror Cap’n Proto’s C++ AnyReader/AnyBuilder, keeping the two languages’ generated APIs consistent – a primary motivation for this design.

An incomplete @[...] mapping may leave trailing fields unmapped; an unmapped field reads its default, and setting one panics ("... is not mapped at this use site") – mirroring the C++ codegen’s behavior.

Modules

any_pointer

Untyped pointer that can be cast to any struct, list, or capability type.

any_pointer_list

List of AnyPointers.

capability

Hooks for the RPC system.

capability_list

List of capabilities.

constant

Helper type for generated Struct and List constants.

data

Sequence of bytes.

data_list

List of sequences of bytes.

dynamic_list

Dynamically-typed lists.

dynamic_struct

Dynamically-typed structs.

dynamic_value

Dynamically typed values.

enum_list

List of enums.

introspect

Traits and types to support run-time type introspection, i.e. reflection.

io

Custom I/O traits that roughly mirror std::io::{Read, BufRead, Write}. This extra layer of indirection enables support of no-std environments.

list_list

List of lists.

message

Untyped root container for a Cap’n Proto value.

primitive_list

List of primitives.

private

Implementation details that should never be directly used by clients.

raw

Functions providing low level access to encoded data.

schema

Convenience wrappers of the datatypes defined in schema.capnp.

schema_capnp

Code generated from schema.capnp.

serialize

Reading and writing of messages using the standard stream framing.

serialize_packed

Reading and writing of messages using the packed stream encoding.

struct_list

List of structs.

text

UTF-8 encoded text.

text_list

List of strings containing UTF-8 encoded text.

traits

Macros

generated_code

Macro for importing Rust code that has been generated by capnpc::CompilerCommand.

Structs

Error

Describes an arbitrary error that prevented an operation from completing.

MessageSize

Size of a message. Every generated struct has a method .total_size() that returns this.

NotInSchema

An enum value or union discriminant that was not found among those defined in a schema.

Word

8 bytes, aligned to an 8-byte boundary.

Enums

ErrorKind

The general nature of an error. The purpose of this enum is not to describe the error itself, but rather to describe how the client might want to respond to the error.

OutputSegments

Helper struct that allows MessageBuilder::get_segments_for_output() to avoid heap allocations in the single-segment case.

Functions

word

Constructs a word with the given bytes.

Type Aliases

Result

Because messages are lazily validated, the return type of any method that reads a pointer field must be wrapped in a Result.