Struct Journal 

pub struct Journal<E: Context, A> { /* private fields */ }

Implementation of super::Mutable for fixed-size value journals.

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 is performed during init.

Implementations

impl<E: Context, A: CodecFixedShared> Journal<E, A>

pub const CHUNK_SIZE: NonZeroUsize

Size of each entry in bytes. Evaluating this rejects zero-size item types at compile time, which would otherwise divide by zero in the chunk math.

pub const CHUNK_SIZE_U64: u64

Size of each entry in bytes (as u64).

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. The replay method can be used to iterate over all items in the Journal.

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

Initialize a Journal in a fully-pruned state at size: existing data is cleared and the journal behaves as if size items were appended then pruned. It is empty (bounds is size..size) and the next append writes at position size. Used for state sync.

Crash Safety

In the event of a crash during this call, upon restart recovery will ensure the journal is either still in its prior state, or has bounds size..size.

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

Durably persists the current state of the structure.

Does not advance the recovery watermark, so external consumers may need to replay entries beyond the previous sync(). Use sync() to advance the watermark and to ensure that a crash after this call doesn’t require any recovery.

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

Durably persist the current state of the structure, ensuring no recovery is required in the event of a crash following this call.

Advances the recovery watermark to the current size.

pub async fn snapshot(&mut self) -> Result<Reader<'static, E, A>, Error>

Capture an owned snapshot (Reader) over the current journal. Bounds are frozen at creation, and the snapshot stays readable across concurrent appends and prunes.

If the journal later rewinds or truncates into the returned reader’s range, subsequent reads from that range may observe unspecified contents.

pub const fn size(&self) -> u64

Return the total number of items in the journal, irrespective of pruning. The next value appended to the journal will be at this position.

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

Append a new item to the journal, returning its position.

Errors

Returns an error if the underlying storage operation fails.

pub async fn append_many<'a>( &'a mut self, items: Many<'a, A>, ) -> Result<u64, Error>

Append items to the journal, returning the position of the last item appended.

Returns Error::EmptyAppend if items is empty.

pub fn prepare_append(&self, items: Many<'_, A>) -> PreparedAppend<A>

Encode items into a buffer that can be appended later with Self::append_prepared.

This lets callers serialize borrowed items synchronously, release those borrows, and perform the append without holding unrelated locks across journal I/O.

pub async fn append_prepared( &mut self, prepared: PreparedAppend<A>, ) -> Result<u64, Error>

Append items encoded by Self::prepare_append, returning the position of the last item appended.

Returns Error::EmptyAppend if prepared contains no items.

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

Rewind the journal to the given size. Returns Error::InvalidRewind if size is beyond the current size, or Error::ItemPruned if it precedes the pruning boundary. The journal is not synced after rewinding.

Warnings

• This operation is not guaranteed to survive restarts until commit() or sync() is called.
• This operation is not atomic. Its on-disk updates are ordered (blobs removed newest-to-oldest) so that restart recovery always rebuilds a contiguous retained prefix.
• Readers returned by snapshot may observe unspecified contents if this rewind truncates into their range.

pub const fn pruning_boundary(&self) -> u64

Return the location before which all items have been pruned.

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

Allow the journal to prune items older than min_item_pos. The journal may not prune all such items in order to preserve blob boundaries, but the amount of such items will always be less than the configured number of items per blob. Returns true if any items were pruned.

Readers holding earlier snapshots keep reading pruned blobs through their own handles; later snapshots observe Error::ItemPruned.

Note that this operation may NOT be atomic, however it’s guaranteed not to leave gaps in the event of failure as items are always pruned in order from oldest to newest.

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

Remove any persisted data created by the journal.

Crash Safety

This operation is intended for final teardown and is not crash-safe. If interrupted, reopening the same partition may observe partially removed state. Use Self::init_at_size for a recoverable reset.

Trait Implementations

impl<E: Context, A: CodecFixedShared> Contiguous for Journal<E, A>

type Item = A

The type of items stored in the journal.

fn bounds(&self) -> Range<u64>

Returns [start, end) with a guaranteed stable pruning boundary.

async fn read(&self, pos: u64) -> Result<A, Error>

Read the item at the given position.

async fn read_many(&self, positions: &[u64]) -> Result<Vec<A>, Error>

Read multiple items at the given positions, which must be strictly increasing.

fn try_read_sync(&self, pos: u64) -> Option<A>

Read an item if it can be done synchronously (e.g. without I/O), returning None otherwise. Decode failures surface as None and the async read path reports the error.

fn try_read_many_sync(&self, positions: &[u64]) -> Vec<Option<A>>

Probe multiple strictly increasing positions, serving those that can be read synchronously (e.g. from a page cache) and returning one slot per position. Positions that require I/O, fail to decode, or fall outside bounds() decline to None. The async read paths are the sole error authority for declined positions.

async fn replay( &self, start_pos: u64, buffer: NonZeroUsize, ) -> Result<impl Stream<Item = Result<(u64, A), Error>> + Send, Error>

Return a stream of all items starting from start_pos, bounded by bounds().

impl<E: Context, A: CodecFixedShared> Inner<E> for Journal<E, A>

Available on neither commonware_stability_BETA nor commonware_stability_DELTA nor commonware_stability_EPSILON nor commonware_stability_GAMMA nor commonware_stability_RESERVED.

type Config = Config

The configuration needed to initialize this journal.

async fn init<F: Family, H: Hasher, S: Strategy>( context: E, merkle_cfg: Config<S>, journal_cfg: Self::Config, rewind_predicate: fn(&A) -> bool, bagging: Bagging, ) -> Result<Journal<F, E, Self, H, S>, Error<F>>

Initialize an authenticated Journal backed by this journal type.

impl<E: Context, A: CodecFixedShared> Mutable for Journal<E, A>

async fn append(&mut self, item: &Self::Item) -> Result<u64, Error>

Append a new item to the journal, returning its position.

async fn append_many<'a>( &'a mut self, items: Many<'a, Self::Item>, ) -> Result<u64, Error>

Append items to the journal, returning the position of the last item appended.

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

Prune items at positions strictly less than min_position.

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

Rewind the journal to the given size, discarding items from the end.

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

Durably persist the journal, guaranteeing the current state will survive a crash.

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

Durably persist the journal, guaranteeing the current state will survive a crash, and that no recovery will be needed on startup.

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

Destroy the journal, removing all associated storage.

fn rewind_to<'a, P>( &'a mut self, predicate: P, ) -> impl Future<Output = Result<u64, Error>> + Send + 'a

where P: FnMut(&Self::Item) -> bool + Send + 'a,

Rewinds the journal to the last item matching predicate. If no item matches, the journal is rewound to the pruning boundary, discarding all unpruned items.