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.

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_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 always proceed while the returned handle is pending, and appends proceed while they fit in the write buffer (a buffer flush or rollover waits for the in-flight fsync). Dropping the handle does not cancel the 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.

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

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 async fn rewind(self, size: u64) -> Result<Self, Error>

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

Errors

Returns Error::InvalidRewind if size is larger than current size. Returns Error::ItemPruned if size is smaller than the pruning boundary.

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 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.

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> 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 Config = Config

The configuration needed to initialize this journal.

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

Initialize the journal from its configuration.

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, read_options: ReadOptions, ) -> 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> 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 rewind(self, size: u64) -> Result<Self, Error>

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

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.

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

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

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