Struct Journal 

pub struct Journal<E: Storage + Metrics, V: Codec> { /* private fields */ }

Implementation of Journal storage.

Implementations

impl<E: Storage + Metrics, V: Codec> Journal<E, V>

pub async fn init(context: E, cfg: Config<V::Cfg>) -> Result<Self, Error>

Initialize a new Journal instance.

All backing blobs are opened but not read during initialization. The replay method can be used to iterate over all items in the Journal.

pub async fn replay( &self, start_section: u64, offset: u32, buffer: NonZeroUsize, ) -> Result<impl Stream<Item = Result<(u64, u32, u32, V), Error>> + '_, Error>

Returns an ordered stream of all items in the journal starting with the item at the given start_section and offset into that section. Each item is returned as a tuple of (section, offset, size, item).

Repair

Like sqlite and rocksdb, the first invalid data read will be considered the new end of the journal (and the underlying Blob will be truncated to the last valid item).

pub async fn append( &mut self, section: u64, item: V, ) -> Result<(u32, u32), Error>

Appends an item to Journal in a given section, returning the offset where the item was written and the size of the item (which may now be smaller than the encoded size from the codec, if compression is enabled).

Warning

If there exist trailing bytes in the Blob of a particular section and replay is not called before this, it is likely that subsequent data added to the Blob will be considered corrupted (as the trailing bytes will fail the checksum verification). It is recommended to call replay before calling append to prevent this.

pub async fn get(&self, section: u64, offset: u32) -> Result<V, Error>

Retrieves an item from Journal at a given section and offset.

Errors

• Error::AlreadyPrunedToSection if the requested section has been pruned during the current execution.
• Error::SectionOutOfRange if the requested section is empty (i.e. has never had any data appended to it, or has been pruned in a previous execution).
• An invalid offset for a given section (that is, an offset that doesn’t correspond to a previously appended item) will result in an error, with the specific type being undefined.

pub async fn get_exact( &self, section: u64, offset: u32, size: u32, ) -> Result<V, Error>

Retrieves an item from Journal at a given section and offset with a given size.

pub async fn size(&self, section: u64) -> Result<u64, Error>

Gets the size of the journal for a specific section.

Returns 0 if the section does not exist.

pub async fn rewind_to_offset( &mut self, section: u64, offset: u32, ) -> Result<(), Error>

Rewinds the journal to the given section and offset, removing any data beyond it.

Warnings

• This operation is not guaranteed to survive restarts until sync is called.
• This operation is not atomic, but it will always leave the journal in a consistent state in the event of failure since blobs are always removed in reverse order of section.

pub async fn rewind(&mut self, section: u64, size: u64) -> Result<(), Error>

Rewinds the journal to the given section and size.

This removes any data beyond the specified section and size.

Warnings

• This operation is not guaranteed to survive restarts until sync is called.
• This operation is not atomic, but it will always leave the journal in a consistent state in the event of failure since blobs are always removed in reverse order of section.

pub async fn rewind_section( &mut self, section: u64, size: u64, ) -> Result<(), Error>

Rewinds the section to the given size.

Unlike Self::rewind, this method does not modify anything other than the given section.

Warning

This operation is not guaranteed to survive restarts until sync is called.

pub async fn sync(&self, section: u64) -> Result<(), Error>

Ensures that all data in a given section is synced to the underlying store.

If the section does not exist, no error will be returned.

pub async fn prune(&mut self, min: u64) -> Result<bool, Error>

Prunes all sections less than min. Returns true if any sections were pruned.

pub async fn close(self) -> Result<(), Error>

Syncs and closes all open sections.

pub fn oldest_section(&self) -> Option<u64>

Returns the number of the oldest section in the journal.

pub async fn destroy(self) -> Result<(), Error>

Removes any underlying blobs created by the journal.