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 above the recovery watermark’s acknowledged prefix is considered the new end of the journal (and the underlying blob is truncated to the last valid item). Data at or below that prefix is never repaired: a blob that no longer backs its acknowledged items fails init, and other damage there surfaces as a read error. Repair is performed during init.

Mutating functions consume the journal and return it only on success: an error (or a dropped future) destroys the handle.

Implementations

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

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

Initialize a new Journal instance.

All backing blobs are opened during initialization. Recovery scans the two newest blobs, skipping blobs and pages the checkpoint watermark already acknowledges, and truncates each to the whole items backed by valid pages. The replay method can be used to iterate over all items in the Journal.

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

Open a retained prefix containing at most max_size items, including pruned positions.

A cap above the recovered end preserves that end. A cap below the retained start returns Error::ItemPruned. Successful initialization durably discards the suffix. Subsequent appends may exceed the cap.

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(self) -> Result<Self, Error>

Durably persists the current state of the structure.

Does not advance the recovery watermark, so reopen may replay entries above it. Use sync() to advance the watermark and to ensure that a crash after this call doesn’t require any recovery.

pub async fn start_sync(self) -> Result<(Self, Handle<()>), Error>

Begin durably persisting the current state of the structure.

Awaiting the returned Handle guarantees state appended before this call survives a crash. Also tries to advance the recovery watermark to the previous proven durable size, bounding startup recovery. Only sync() guarantees a current watermark.

At most one data sync and one watermark sync are in flight at a time: this call waits for the prior call’s syncs before starting new ones. It does not wait for a pending rollover fsync: the returned handle joins it, so an earlier call’s handle may still be pending when this call returns. Reads proceed while the returned handle is pending, and appends proceed while they fit in the write buffer.

Flush errors are returned directly. Dropping the handle does not cancel the sync or lose its failure: a later operation reports it, no later than the next Self::sync.

pub async fn sync(self) -> Result<Self, 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(self) -> Result<(Self, 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. It keeps the journal’s blobs open, so reopening a partition that still holds one of them fails while the snapshot is alive.

pub 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(self, item: &A) -> Result<(Self, 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(self, items: Many<'_, A>) -> Result<(Self, 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( self, prepared: PreparedAppend<A>, ) -> Result<(Self, 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 fn pruning_boundary(&self) -> u64

Return the location before which all items have been pruned.

pub async fn prune(self, min_item_pos: u64) -> Result<(Self, 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. A started sync that failed is reported before anything is removed.

Crash Safety

An interrupted destroy leaves a journal that reopens either as a crash would recover it or as a fresh journal at position zero, and that a retried destroy removes.

Trait Implementations

impl<E: Context, A: CodecFixedShared> Backing<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 Recovery = Recovery<E, A>

Initialization-owned storage used to select and validate the retained prefix.

type Config = Config

The configuration needed to initialize this journal.

async fn recover( context: E, cfg: Self::Config, max_size: Option<u64>, ) -> Result<Self::Recovery, Error>

Open recovery storage for an optional exclusive item end. Implementations may inspect later storage to validate recovery boundaries. Returns JournalError::ItemPruned when max_size lies below the retained start.

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

Open recovery storage reset to an empty journal at size, discarding stored items without reading them. Returns JournalError::SizeOverflow for u64::MAX.

async fn span(context: E, cfg: &Self::Config) -> Result<Range<u64>, Error>

Positions stored items may occupy, determined without reading them.

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, range: Range<u64>, buffer: NonZeroUsize, read_options: ReadOptions, ) -> Result<impl Stream<Item = Result<Batch<A>, Error>> + Send, Error>

Return a stream of the items in range as Batches of consecutive items, in position order. range must fall within bounds(). An empty range within bounds() yields an empty stream.

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

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

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

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

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

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

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

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

Prune items at positions strictly less than min_position.

async fn start_sync(self) -> Result<(Self, Handle<()>), Error>

Begin durably persisting the current state of the journal.

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

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

async fn sync(self) -> Result<Self, 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.