package capnp

  1. Overview
  2. Docs

Module ROM.Message

include MessageSig.MESSAGE with type 'a segment_t := 'a Segment.t
type storage_t

storage_t is the type of the underlying storage associated with this segment (e.g. "bytes").

type storage_descr_t = {
  1. segment : storage_t;
  2. bytes_consumed : int;
}
type -'cap t

'cap t is the type of a message. The 'cap annotation is type ro for read-only segments, and type rw for read/write segments.

val create : int -> MessageSig.rw t

create size allocates a new zero-filled single-segment message of at least size bytes, raising an exception if storage cannot be allocated.

val release : 'cap t -> unit

release m immediately releases the storage for all segments of message m, potentially making the storage available for future allocations. After releasing a storage segment, the behavior of the accessor functions is undefined.

val num_segments : 'cap t -> int

num_segments m obtains the number of segments associated with message m.

val total_size : 'cap t -> int

total_size m gets the total size of the message, in bytes, across all segments.

val total_alloc_size : 'cap t -> int

total_alloc_size m gets total size of the underlying storage for the message, in bytes, across all segments. (This is at least as large as the value returned by total_size.

val get_segment : 'cap t -> int -> 'cap Segment.t

get_segment m i gets zero-indexed segment i associated with message m.

val readonly : 'cap t -> MessageSig.ro t

readonly m obtains a view of message m which is read-only qualified.

val of_storage : storage_t list -> MessageSig.rw t

of_storage chunks constructs a read/write message which uses the list of storage chunks as the underlying storage media for the message segments.

val to_storage : 'cap t -> storage_descr_t list

to_storage m retrieves a list of the storage elements associated with the message segments.

val with_message : 'cap t -> f:('cap t -> 'a) -> 'a

with_message m ~f first evaluates f m, then invokes release m, then returns the result of the application of f. If f m raises an exception, the exception will be propagated after a call to release.

val with_attachments : MessageSig.attachments -> 'cap t -> 'cap t

with_attachments attachments m is a message sharing the same storage as m, but with the given attachments. If m is mutable, it should not be used after calling this. Effectively, attachments is a constructor argument, but it isn't known until slightly after the message is constructed.

val get_attachments : 'cap t -> MessageSig.attachments

get_attachments m returns the handler previously set in with_attachments, or No_attachments if no attachments were given.