package capnp

create_write_context_for_fd ~compression fd creates a context for writing messages to the given file descriptor using the specified compression format. If restart is set to true (default), then writes failing with error code Unix.EINTR will be automatically restarted.

create_write_context_for_channel ~compression chan creates a context for writing messages to the given buffered output channel using the specified compression format.

create_read_context_for_fd ~compression fd creates a context for reading messages from the given file descriptor using the specified compression method. If restart is set to true (default), then writes failing with error code Unix.EINTR will be automatically restarted.

create_read_context_for_channel ~compression chan creates a context for reading messages from the given input channel using the specified compression method.

write_message_to_fd ~compression message fd writes the specified message to the given file descriptor, using the specified compression method. If restart is set to true (default), then writes failing with error code Unix.EINTR will be automatically restarted.

EAGAIN/EWOULDBLOCK are handled automatically.

• raises Unix.Unix_error

  if a write fails

write_message_to_channel ~compression message chan writes the specified message to the given buffered I/O channel, using the specified compression method.

write_message_to_file ~compression message filename writes the specified message to a file with the given filename, using the requested compression method. The optional perm specifies the file creation mode, in case a new file must be created.

As write_message_to_file, but the file is constructed transactionally by writing to a temporary file and renaming to the filename, and Unix.fsync is used carefully to ensure durability of the write.

The overhead of rename and fsync may lead to reduced throughput relative to write_message_to_file.

• raises Unix.Unix_error

  if write, fsync, or rename operations fail.

read_single_message_from_fd ~compression fd attempts to read a single message from the specified file descriptor, using the given compression method. If restart is set to true (default), then writes failing with error code Unix.EINTR will be automatically restarted.

EAGAIN/EWOULDBLOCK are handled automatically.

This function is appropriate to use only when 0 or 1 messages are expected to be available from the descriptor; if additional messages are available, some message data could be lost. Use create_XXX_read_context_for_fd to correctly handle a stream of messages.

• returns

  Some message, or None if end-of-file was reached before a message could be decoded.

• raises Unix.Unix_error

  if a read fails

• raises Unsupported_message_frame

  if the frame header describes a segment count or segment size that is too large for the implementation

read_single_message_from_channel ~compression chan attempts to read a single message from the specified input channel, using the given compression method.

This function is appropriate to use only when 0 or 1 messages are expected to be available from the channel; if additional messages are available, some message data could be lost. Use create_XXX_read_context_for_channel to correctly handle a stream of messages.

• returns

  Some message, or None if end-of-file was reached before a message could be decoded.

• raises Unsupported_message_frame

  if the frame header describes a segment count or segment size that is too large for the implementation

read_message_from_file ~compression filename attempts to read a message from the file with the given filename, using the requested compression method.

• returns

  Some message, or None if the file does not contain a complete message frame.