Skip to main content

Store

pamoja_core::store

Trait Store 

Source 
pub trait Store {
    // Required methods
    fn append(
        &mut self,
        record: &[u8],
    ) -> impl Future<Output = Result<()>> + Send;
    fn peek(&self) -> impl Future<Output = Result<Option<Vec<u8>>>> + Send;
    fn pop(&mut self) -> impl Future<Output = Result<Option<Vec<u8>>>> + Send;
    fn len(&self) -> impl Future<Output = Result<usize>> + Send;

    // Provided methods
    fn append_text(
        &mut self,
        text: &str,
    ) -> impl Future<Output = Result<()>> + Send { ... }
    fn peek_text(&self) -> impl Future<Output = Result<Option<String>>> + Send
       where Self: Sync { ... }
    fn pop_text(
        &mut self,
    ) -> impl Future<Output = Result<Option<String>>> + Send
       where Self: Send { ... }
    fn is_empty(&self) -> impl Future<Output = Result<bool>> + Send
       where Self: Sync { ... }
}
Expand description

A durable, first-in first-out queue for store-and-forward buffering.

Records are appended while a device is offline and drained in order when a link becomes available, letting applications tolerate intermittent connectivity without losing data.

The returned futures are Send, for the same reason a Transport’s are: a transport ladder buffers into a store and is itself a transport, so a task on a multi-threaded runtime can drive it. An implementation written as async fn satisfies this as long as everything it holds across an await is Send.

Required Methods§

Source

fn append(&mut self, record: &[u8]) -> impl Future<Output = Result<()>> + Send

Appends a record to the back of the queue.

§Arguments
  • record - the raw bytes to persist.
§Returns

Ok(()) once the record is durably stored.

§Errors

Returns Error::Io if the record cannot be written to durable storage.

Source

fn peek(&self) -> impl Future<Output = Result<Option<Vec<u8>>>> + Send

Returns the oldest record without removing it.

This lets a forwarder send a record before committing to its removal, so a failed send can leave the record buffered in order rather than dropping it.

§Returns

Some(record) containing the oldest buffered bytes, or None if the queue is empty.

§Errors

Returns Error::Io if the queue cannot be read.

Source

fn pop(&mut self) -> impl Future<Output = Result<Option<Vec<u8>>>> + Send

Removes and returns the oldest record in the queue.

§Returns

Some(record) containing the oldest buffered bytes, or None if the queue is empty.

§Errors

Returns Error::Io if the queue cannot be read.

Source

fn len(&self) -> impl Future<Output = Result<usize>> + Send

Returns the number of records currently buffered.

§Returns

The count of records waiting to be drained.

§Errors

Returns Error::Io if the queue length cannot be determined.

Provided Methods§

Source

fn append_text(&mut self, text: &str) -> impl Future<Output = Result<()>> + Send

Appends text to the back of the queue: a reading or a line written out.

This is append with the text’s UTF-8 bytes, so a queue of readings needs no encoding step; peek_text and pop_text read them back.

§Arguments
  • text - the text to persist.
§Returns

Ok(()) once the record is durably stored.

§Errors

Whatever append returns.

Source

fn peek_text(&self) -> impl Future<Output = Result<Option<String>>> + Send
where Self: Sync,

Returns the oldest record as text, without removing it.

It borrows the store across an await, so it asks for Sync, which a store whose own futures are Send already is.

§Returns

Some(text) for the oldest record, or None if the queue is empty.

§Errors

Whatever peek returns, or Error::Codec if the record is not UTF-8 text.

Source

fn pop_text(&mut self) -> impl Future<Output = Result<Option<String>>> + Send
where Self: Send,

Removes and returns the oldest record as text.

§Returns

Some(text) for the oldest record, or None if the queue is empty.

§Errors

Whatever pop returns, or Error::Codec if the record is not UTF-8 text.

Source

fn is_empty(&self) -> impl Future<Output = Result<bool>> + Send
where Self: Sync,

Returns whether the queue currently holds no records.

The default implementation reports whether len is zero. It borrows the store across an await, so it asks for Sync, which a store whose own futures are Send already is.

§Returns

true if the queue is empty, false otherwise.

§Errors

Returns Error::Io if the queue length cannot be determined.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§