Struct capnp_nonblock::MessageStream

pub struct MessageStream<S, A = HeapAllocator, M = Builder<A>> { /* fields omitted */ }

A MessageStream wraps a stream, and provides methods to read and write Cap'n Proto messages to the stream. MessageStream performs its own internal buffering, so the provided stream need not be buffered.

If the underlying stream is non-blocking, MessageStream will automatically pause reading and writing messages, and will resume during the next call to read_message or write.

MessageStream attempts to reduce the number of required allocations when reading messages by allocating memory in large chunks, which it loans out to messages via reference counting. The reference counting is not thread safe, so messages read by MessageStream may not be sent or shared across thread boundaries.

Methods

impl<S, M, A> MessageStream<S, M, A>

fn new(inner: S, options: ReaderOptions) -> MessageStream<S, M, A>

Creates a new MessageStream instance wrapping the provided stream, and with the provided reader options.

fn outbound_queue_len(&self) -> usize

Returns the number of queued outbound messages.

fn clear_outbound_queue(&mut self)

Clears the outbound message queue of all messages that have not begun writing yet.

fn inner_mut(&mut self) -> &mut S

Returns the inner stream.

fn inner(&self) -> &S

Returns the inner stream.

impl<S, M, A> MessageStream<S, M, A> where
    S: Read, 

fn read_message(&mut self) -> Result<Option<Reader<Segments>>>

Returns the next message from the stream, or None if the entire message is not yet available.

If an Err result is returned, then the stream must be considered corrupt, and read_message must not be called again.

impl<S, A, M> MessageStream<S, A, M> where
    S: Write,
    M: Borrow<Builder<A>>,
    A: Allocator, 

fn write(&mut self) -> Result<()>

Writes queued messages to the stream. This should be called when the stream is in non-blocking mode and writable.

If an Err result is returned, then the stream must be considered corrupt, and write or write_message must not be called again.

fn write_message(&mut self, message: M) -> Result<()>

Queue message for write.

This method optimistically begins writing to the stream if there is no message currently being written. This is necessary for the blocking stream case, and efficient in the non-blocking case as well, since it is likely that the stream is writable.

If an Err result is returned, then the stream must be considered corrupt, and write or write_message must not be called again.

Trait Implementations

impl<S, A, M> Debug for MessageStream<S, A, M> where
    S: Debug, 

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.