Struct chronicle::queue::DocumentContext

#[repr(C)]
pub struct DocumentContext { /* private fields */ }

A DocumentContext encapulates a single, atomic message in Queue, with a read/write context handle obtained from an ExcerptTailer or ExcerptAppender respectively.

Scoped document contexts are provided for RAII-style use and automatically close the document when they are dropped. It is recommended that scoped documents are used rather than DocumentContext instances directly.

An attempted write can be abandoned without persisting any change to the queue by calling rollback_on_close() prior to the DocumentContext closing (either explicitly via close or automatically when a corresponding scoped document is dropped).

Note: When writing to a Queue, a write lock is held for the duration of the corresponding DocumentContext. The lock is released when the DocumentContext is closed (either explicitly via close or automatically when a corresponding scoped document is dropped).

Example

let appender = queue.acquire_appender().unwrap();
{
    let context = appender.scoped_writing_document();
    // write lock acquired
    // add data to the queue as needed
    // data will be stored as a single atomic message
    ...
    // context is dropped when the scope closes
    // at this point the data is formally committed to the queue
    // and the write lock is released.
    // The message then becomes visible (atomically) to other users.
}

let tailer = queue.create_tailer().unwrap();
{
    let context = tailer.scoped_reading_document();
    // no locks for readers (no contention/back-pressure on writers)
    // context brackets a single atomic message, eg as written above
}

Implementations

impl DocumentContext

pub fn is_present(&self) -> bool

A read from the end of a Queue - or an empty Queue - will return a DocumentContext which sets an internal “not present” flag to indicate that there is no message contained in the context.

This method should be called on any received DocumentContext to check this state prior to processing.

Example

let context = tailer.scoped_reading_document();
if context.is_present() {
    // process the message
}

impl DocumentContext

pub fn meta_data(&self, meta_data: bool)

A DocumentContext can optionally be set as metadata rather than data (the default).

This feature allows both types of message to be contained in a single Queue, and can be used for example to mix auxiliary data amongst message data. Readers of the queue can then test whether any given message is metadata or normal data, and handle each differently

This function can be used to set or clear the metadata flag for a given message.

Arguments

• meta_data: bool, true to set as metadata, false to set as normal data

impl DocumentContext

pub fn is_meta_data(&self) -> bool

Test if this DocumentContextis flagged as metadata

impl DocumentContext

pub fn is_data(&self) -> bool

Combined test that this DocumentContext is valid and has data

Equivalent to is_present() && !is_meta_data()

impl DocumentContext

pub fn wire(&self) -> &Wire

Get a handle to a Wire handle which wraps the content of this DocumentContext.

The Wire handle can then be used to read or write the data using [Bytes] or ValueIn or ValueOut, either as terse or flexible data as described in more detail in the linked sections.

impl DocumentContext

pub fn rollback_on_close(&self)

A write attempt associated with a given DocumentContext can optionally be abandoned, leaving the queue in the same state as before the write was attempted. This is an atomic action and safe with concurrent writers or readers.

To abandon a write attempt, call this function at any time prior to closing the DocumentContext (either explicitly via close() or automatically when a scoped write context is dropped)

Less commonly, a read attempt can also be abandoned, leaving the tailer/reader in the same state and read position as before the read was attempted

impl DocumentContext

pub fn close(&self)

Close this DocumentContext.

If this DocumentContext is a writer, this call atomically commits any changes to the queue (provided rollback_on_close() has not been called) and releases the write lock.

If this DocumentContext is a reader, the read position is advanced to the next message (provided rollback_on_close() has not been called)

Note: this call would rarely be called explicitly. It is recommended to used scoped document contexts which automatically close the queue when dropped

impl DocumentContext

pub fn index(&self) -> i64

Items written to a Queue have unique indexes. This call returns the index of the most recent message read or written by this DocumentContext

impl DocumentContext

pub fn bytes(&self) -> &Bytes

Get a handle to the message Bytes for this DocumentContext

Data can then be read or written (depending on the DocumentContext type) using the methods described in Bytes

Example

let context = appender.writing_document();
let bytes = context.bytes();
bytes.write_string("incomplete longer write");

Trait Implementations

impl Closeable for DocumentContext

fn close(&self)

impl ExternType for DocumentContext

type Kind = Opaque

Either cxx::kind::Opaque or cxx::kind::Trivial.

type Id

A type-level representation of the type’s C++ namespace and type name.