Module ecapnp

The highlevel Cap'n Proto API.

Copyright 2013, Andreas Stenius

Authors: Andreas Stenius (kaos@astekk.se).

Description

The highlevel Cap'n Proto API.

This module doesn't implement any functionality, it is simply exposing the highlevel functions from the other modules.

Data Types

annotation()

annotation() = #annotation{type = any(), targets = [atom()]}

Describes an annotation type.

bit_count()

bit_count() = non_neg_integer()

const()

const() = #const{}

A schema const value.

data()

data() = #data{type = undefined | term(), align = ecapnp:bit_count(), default = undefined | ecapnp:value()}

Describes a data field within a struct.

element_size()

element_size() = empty | bit | byte | twoBytes | fourBytes | eightBytes | pointer | inlineComposite

The data size for the values in a list.

In case of inlineComposite the list data is prefixed with a tag word describing the layout of the element data. The tag is in the same format as a struct ref, except the offset field indicates the number of elements in the list.

enum()

enum() = #enum{values = ecapnp:enum_values()}

Describes the schema for a enum type.

enum_values()

enum_values() = [{integer(), atom()}]

A list of tuples, pairing the enumerants ordinal value with its name.

far_ref()

far_ref() = #far_ref{segment = non_neg_integer(), double_far = boolean()}

field_name()

field_name() = atom()

field_type()

field_type() = data() | ptr() | group()

field_value()

field_value() = any()

group()

group() = #group{id = ecapnp:type_id()}

Declares the type of group for a struct field.

interface()

interface() = #interface{extends = list(), methods = list()}

Describes the schema for a interface type.

list_ref()

list_ref() = #list_ref{size = ecapnp:bit_count() | pointer | {inlineComposite, #struct_ref{dsize = ecapnp:word_count(), psize = ecapnp:ptr_count()}}, count = non_neg_integer()}

The reference is a pointer to a list.

message()

message() = [binary()]

Holds all the segments in a Cap'n Proto message.

This is the raw segment data, no segment headers or other information is present.

object()

object() = #object{ref = #ref{segment = undefined | ecapnp:segment_id(), pos = ecapnp:segment_pos(), offset = ecapnp:segment_offset(), align = ecapnp:bit_count(), kind = ecapnp:ref_kind(), data = undefined | #builder{pid = undefined | pid()} | #reader{data = undefined | [binary()] | binary(), caps = list()}}, schema = undefined | atom() | ecapnp:schema_node()}

A reference paired with schema type information.

ptr()

ptr() = #ptr{type = undefined | term(), idx = ecapnp:ptr_index(), default = ecapnp:value()}

Describes a pointer field within a struct.

ptr_count()

ptr_count() = non_neg_integer()

ptr_index()

ptr_index() = non_neg_integer()

ref()

ref() = #ref{segment = undefined | ecapnp:segment_id(), pos = ecapnp:segment_pos(), offset = ecapnp:segment_offset(), align = ecapnp:bit_count(), kind = ecapnp:ref_kind(), data = undefined | #builder{pid = undefined | pid()} | #reader{data = undefined | [binary()] | binary(), caps = list()}}

A reference instance.

If pos is -1, then the instance has no allocated space in the message, but may still point to a valid location within a segment. Note, the value of pos should still be used even when pos is -1.

To get the position of the data the reference points to: DataPos = R#ref.pos + R#ref.offset + 1.

ref_kind()

ref_kind() = null | struct_ref() | list_ref() | far_ref()

schema()

schema() = #schema_node{module = undefined | atom(), name = undefined | ecapnp:type_name(), id = ecapnp:type_id(), src = ecapnp:text(), kind = file, annotations = list(), nodes = ecapnp:schema_nodes(), scope = ecapnp:type_id()}

The top-level schema node (for the .capnp-file).

schema_kind()

schema_kind() = file | struct() | enum() | interface() | const() | annotation()

schema_node()

schema_node() = #schema_node{module = undefined | atom(), name = undefined | ecapnp:type_name(), id = ecapnp:type_id(), src = ecapnp:text(), kind = ecapnp:schema_kind(), annotations = list(), nodes = ecapnp:schema_nodes(), scope = ecapnp:type_id()}

Each schema node within a file.

schema_nodes()

schema_nodes() = [schema_node()]

schema_type()

schema_type() = type_name() | type_id()

segment_id()

segment_id() = integer()

segment_offset()

segment_offset() = integer()

segment_pos()

segment_pos() = -1 | non_neg_integer()

struct()

struct() = #struct{dsize = ecapnp:word_count(), psize = ecapnp:ptr_count(), esize = ecapnp:element_size(), union_field = none | ecapnp:field_type(), fields = ecapnp:struct_fields()}

Describes the schema for a struct type.

dsize
The size of the struct's data section, in words.
psize
The number of pointers in the struct.
esize
The list element size for the struct.
union_field
Describes the unnamed union in the struct, or none if there is no unnamed union in the struct.
fields
Describes all the fields in the struct.

struct_fields()

struct_fields() = [field_type()]

struct_ref()

struct_ref() = #struct_ref{dsize = ecapnp:word_count(), psize = ecapnp:ptr_count()}

The reference is a pointer to a struct.

dsize and psize specifies the data size and pointer count actually allocated in the message. This may not match those expected by the schema. Any data in the message that is outside of what the schema expects will be unreachable by application code, while any reads outside of the allocated data will result in a default value back. Thus the missmatch is transparent in application code.

text()

text() = binary()

The required NULL byte suffix is automatically taken care of by ecapnp_ref for text values.

type_id()

type_id() = integer()

type_name()

type_name() = atom()

value()

value() = number() | boolean() | [value()] | binary() | null

value_type()

value_type() = void | bool | float32 | float63 | uint8 | uint16 | uint32 | uint64 | int8 | int16 | int32 | int64

word_count()

word_count() = non_neg_integer()

Note that in Cap'n Proto, a word is 8 bytes (64 bits).

Function Index

const/2Get const value from schema.
get/1Read the unnamed union value of object.
get/2Read the field value of object.
get_root/2
get_root/3Get the root object for a message.
init/2
init/3
request/2
send/1
set/2Write union value to the unnamed union of object.
set/3Write value to a field of object.
set_root/1
set_root/2Set the root object for a new message.
wait/1
wait/2

Function Details

const/2

const(Name::type_name() | type_id(), Schema::schema()) -> value()

Get const value from schema.

get/1

get(Object::object()) -> {field_name(), field_value()} | field_name()

Read the unnamed union value of object. The result value is either a tuple, describing which union tag it is, and its associated value, or just the tag name, if the value is void.

See also: ecapnp_get:union/1.

get/2

get(Field::field_name(), Object::object()) -> field_value()

Read the field value of object.

See also: ecapnp_get:field/2.

get_root/2

get_root(Schema, Segments) -> any()

get_root/3

get_root(Type::type_name(), Schema::schema(), Segments::message()) -> {ok, Root::object()}

Get the root object for a message. The message should already have been unpacked and parsed.

See also: ecapnp_get:root/3, ecapnp_message:read/1, ecapnp_serialize:unpack/1.

init/2

init(Value, Object) -> any()

init/3

init(Field, Type, Object) -> any()

request/2

request(Name, ObjCap) -> any()

send/1

send(Rpc_call) -> any()

set/2

set(Value::{field_name(), field_value()} | field_name(), Object::object()) -> ok

Write union value to the unnamed union of object.

See also: ecapnp_set:union/2.

set/3

set(Field::field_name(), Value::field_value(), Object::object()) -> ok

Write value to a field of object.

See also: ecapnp_set:field/3.

set_root/1

set_root(Schema) -> any()

set_root/2

set_root(Type::type_name(), Schema::schema()) -> {ok, Root::object()}

Set the root object for a new message. This creates a new empty message, ready to be filled with data.

To get the segment data out, call ecapnp_message:write/1.

See also: ecapnp_set:root/2.

wait/1

wait(Promise) -> any()

wait/2

wait(Promise, Timeout) -> any()


Generated by EDoc, May 30 2014, 12:56:29.