Struct Journal 

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

A segmented journal with fixed-size entries.

Each section is stored in a separate blob. Within each blob, items are fixed-size.

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). Repair occurs during init by checking each blob’s size.

Implementations

impl<E: Storage + Metrics, A: CodecFixedShared> Journal<E, A>

pub const CHUNK_SIZE: usize = A::SIZE

Size of each entry.

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

Initialize a new Journal instance.

All backing blobs are opened but not read during initialization. Use replay to iterate over all items.

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

Append a new item to the journal in the given section.

Returns the position of the item within the section (0-indexed).

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

Read the item at the given section and position.

Errors

• Error::AlreadyPrunedToSection if the section has been pruned.
• Error::SectionOutOfRange if the section doesn’t exist.
• Error::ItemOutOfRange if the position is beyond the blob size.

pub async fn get_many( &self, section: u64, positions: &[u64], buf: &mut [u8], ) -> Result<(Vec<A>, usize), Error>

Read multiple items from the same section into a caller buffer.

buf must be at least positions.len() * CHUNK_SIZE bytes. All positions must be strictly increasing and within the section’s bounds.

Returns the decoded items and the number served without a blob read (page cache or tip buffer hits).

pub fn try_get_sync(&self, section: u64, position: u64) -> Option<A>

Get an item if it can be done synchronously (e.g. without I/O), returning None otherwise.

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

Read the last item in a section, if any.

Returns Ok(None) if the section is empty.

Errors

• Error::AlreadyPrunedToSection if the section has been pruned.
• Error::SectionOutOfRange if the section doesn’t exist.

pub async fn replay( &mut self, start_section: u64, start_position: u64, buffer: NonZeroUsize, ) -> Result<impl Stream<Item = Result<(u64, u64, A), Error>> + Send + '_, Error>

Returns a stream of all items starting from the given section.

Each item is returned as (section, position, item).

pub async fn sync(&mut self, sections: impl Sections) -> Result<(), Error>

Sync the given sections to storage.

pub async fn start_sync( &mut self, sections: impl Sections, ) -> Result<Handle<()>, Error>

Start syncing the given sections to storage.

pub async fn sync_all(&mut self) -> Result<(), Error>

Sync all sections to storage.

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

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

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

Returns the oldest section number, if any blobs exist.

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

Returns the newest section number, if any blobs exist.

pub fn sections(&self) -> impl Iterator<Item = u64> + '_

Returns an iterator over all section numbers.

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

Returns the number of items in the given section.

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

Returns the byte size of the given section.

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

Rewind the journal to a specific section and byte offset.

This truncates the section to the given size. All sections after section are removed.

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

Rewind only the given section to a specific byte offset.

Unlike rewind, this does not affect other sections.

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

Remove all underlying blobs.

pub async fn clear(&mut self) -> Result<(), Error>

Clear all data, resetting the journal to an empty state.

Unlike destroy, this keeps the journal alive so it can be reused.