Module ecapnp_ref

Read/Write/Allocate references.

Copyright 2013, Andreas Stenius

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

Description

Read/Write/Allocate references.

Everything reference. Which is almost everything in Cap'n Proto :p.

Data Types

ref()

ref() = ecapnp:ref()

ref_kind()

ref_kind() = ecapnp:ref_kind()

segment_id()

segment_id() = ecapnp:segment_id()

word_count()

word_count() = ecapnp:word_count()

Function Index

alloc/3Allocate data for a reference.
alloc/4Allocate data for a reference of a specific kind.
alloc_data/1Allocate data for reference.
alloc_data/2Allocate data for reference.
alloc_list/3Allocate data for list.
copy/1Make a deep copy of a reference.
create_ptr/2
follow_far/1Resolve a far pointer.
get/3Get reference from segment data.
get/4Get reference from segment data.
null_ref/1Get a null pointer.
paste/2Allocate space and write data for reference.
ptr/2Get indexed reference (unintialized).
read_data/1Read data.
read_data/2Read data.
read_list/1Read elements from a list ref.
read_list/2Read elements from a list ref.
read_list_refs/3Read elements from a list ref, forcing the result into a list of refs.
read_struct_data/3Read from data section of a struct ref.
read_struct_data/4Read from data section of a struct ref.
read_struct_ptr/2Read a refeference from the pointer section of struct ref.
read_struct_ptr/3Read a refeference from the pointer section of struct ref.
read_text/1Read text.
read_text/2Read text.
refresh/1Reread reference from message.
set/2Set reference kind.
write_data/3Write data.
write_list/4Write list element.
write_struct_data/4Write to struct data section.
write_struct_ptr/2Write pointer reference.
write_text/3Write text.

Function Details

alloc/3

alloc(SegmentId::segment_id(), Size::integer(), Builder::pid()) -> ref()

Allocate data for a reference.

The allocated data is left empty.

alloc/4

alloc(Kind::ref_kind(), SegmentId::segment_id(), Size::integer(), Builder::pid()) -> ref()

Allocate data for a reference of a specific kind.

The reference will be written to the first word of the allocated data, by set/2.

See also: alloc/3, set/2.

alloc_data/1

alloc_data(Ref::ref()) -> ref()

Allocate data for reference.

The number of words allocated is deduced from the passed Reference.

Returns an updated reference with the offset field updated to point at the newly allocated data.

alloc_data/2

alloc_data(Size::word_count(), Ref::ref()) -> ref()

Allocate data for reference.

alloc_list/3

alloc_list(Idx::integer(), List_ref::ref_kind(), Ref::ref()) -> ref()

Allocate data for list.

Kind should be a #list_ref{} describing the list to allocate; but for inlineComposite lists, the #list_ref.size field should point to a #struct_ref{} describing the list element type, and #list_ref.count should still be the number of elements rather than the total word count.

See also: alloc_data/1.

copy/1

copy(Ref::ref()) -> binary()

Make a deep copy of a reference.

Recursively follows all pointers and copies them as well. So copying a root object will effectively defragment a fragmented message.

create_ptr/2

create_ptr(Offset, Ref) -> any()

follow_far/1

follow_far(Ref::ref()) -> ref()

Resolve a far pointer.

Usually this is done automatically when reading ref's.

get/3

get(SegmentId::segment_id(), Pos::integer(), Data::pid() | binary()) -> ref()

Get reference from segment data.

Read segment, and parse it for a reference pointer.

Will follow far pointers.

See also: get/4.

get/4

get(SegmentId::segment_id(), Pos::integer(), Data::pid() | binary(), FollowFar::boolean()) -> ref()

Get reference from segment data.

Read segment, and parse it for a reference pointer.

The resulting reference may be a far pointer, unless FollowFar is true.

See also: read_segment/5, ecapnp_data:get_segment/4.

null_ref/1

null_ref(Ref::ref()) -> ref()

Get a null pointer.

The up-side with this function in contrast to using a default #ref{} record on its own is that the null reference returned by this function knows about the schema and segment data of the message for which it was based.

paste/2

paste(X1::binary(), Ref::ref()) -> ref()

Allocate space and write data for reference.

All data, both data section and pointers section, and any data that those may refer to (good for saving off a deep copy of another object).

Note: Data should be whole words (8 bytes). Any fraction of a word will be truncated.

ptr/2

ptr(Idx::integer(), Ref::ref()) -> ref()

Get indexed reference (unintialized).

NOTICE: That by 'uninitialized', the returned reference is a null reference, regardless of what data currently is in the segment.

That is, for structs, get a reference for pointer Idx, while for lists, get a reference for the element at Idx (either a pointer or a "unpositioned" ref pointing to where a inlineComposite element holds its data).

read_data/1

read_data(Ref::ref()) -> binary()

Read data.

read_data/2

read_data(Ref::ref(), Default::any()) -> binary() | any()

Read data.

read_list/1

read_list(Ref::ref()) -> [ref()] | [binary()]

Read elements from a list ref.

read_list/2

read_list(Ref::ref(), Default::any()) -> [ref()] | [binary()] | any()

Read elements from a list ref.

read_list_refs/3

read_list_refs(Ref, ElementRefKind, Default) -> any()

Read elements from a list ref, forcing the result into a list of refs.

read_struct_data/3

read_struct_data(Align::integer(), Len::integer(), Ref::ref()) -> binary()

Read from data section of a struct ref.

Align is number of bits into the data section to read from, and Len is number of bits to read.

read_struct_data/4

read_struct_data(FAlign::integer(), Len::integer(), Ref::ref(), Default::any()) -> binary() | any()

Read from data section of a struct ref.

Align is number of bits into the data section to read from, and Len is number of bits to read.

read_struct_ptr/2

read_struct_ptr(Idx::integer(), Ref::ref()) -> ref()

Read a refeference from the pointer section of struct ref.

read_struct_ptr/3

read_struct_ptr(Idx::integer(), Ref::ref(), Default::any()) -> ref() | any()

Read a refeference from the pointer section of struct ref.

read_text/1

read_text(Ref::ref()) -> binary()

Read text.

NOTICE: The required trailing NULL byte is silently dropped when reading the text.

read_text/2

read_text(Ref::ref(), Default::any()) -> binary() | any()

Read text.

NOTICE: The required trailing NULL byte is silently dropped when reading the text.

refresh/1

refresh(Ref::ref()) -> ref()

Reread reference from message.

set/2

set(Kind, Ref) -> any()

Set reference kind.

Updates the reference kind and writes it to the segment data at Ref.pos.

See also: alloc/4.

write_data/3

write_data(Data::binary(), Ptr::ref(), Ref::ref()) -> ok

Write data.

Allocates data for Data and updates the Ptr in Ref to point to the newly allocated (and updated) data.

write_list/4

write_list(Idx::integer(), ElementIdx::integer(), Value::binary(), Ref::ref()) -> ok

Write list element.

write_struct_data/4

write_struct_data(FAlign::integer(), Len::integer(), Value::binary(), Ref::ref()) -> ok

Write to struct data section.

write_struct_ptr/2

write_struct_ptr(Ptr::ref(), Ref::ref()) -> ok

Write pointer reference.

Ptr must be a pointer from Ref (i.e. the pointer is within the data bounds of the reference).

write_text/3

write_text(Text::binary(), Ptr::ref(), Ref::ref()) -> ok

Write text.

Allocates data for Text and updates the Ptr in Ref to point to the newly allocated (and updated) data.

NOTICE: An additional NULL byte is appended to Text to stay conformant with Cap'n Proto specifications.


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