Trait Mutable 

pub trait Mutable: Contiguous + Sized {
    // Required methods
    fn append(
        self,
        item: &Self::Item,
    ) -> impl Future<Output = Result<(Self, u64), Error>> + Send;
    fn append_many(
        self,
        items: Many<'_, Self::Item>,
    ) -> impl Future<Output = Result<(Self, u64), Error>> + Send
       where Self::Item: Sync;
    fn prune(
        self,
        min_position: u64,
    ) -> impl Future<Output = Result<(Self, bool), Error>> + Send;
    fn rewind(
        self,
        size: u64,
    ) -> impl Future<Output = Result<Self, Error>> + Send;
    fn start_sync(
        self,
    ) -> impl Future<Output = Result<(Self, Handle<()>), Error>> + Send;
    fn commit(self) -> impl Future<Output = Result<Self, Error>> + Send;
    fn sync(self) -> impl Future<Output = Result<Self, Error>> + Send;
    fn destroy(self) -> impl Future<Output = Result<(), Error>> + Send;

    // Provided method
    fn rewind_to<P>(
        self,
        predicate: P,
    ) -> impl Future<Output = Result<(Self, u64), Error>> + Send
       where P: FnMut(&Self::Item) -> bool + Send { ... }
}

A Contiguous journal that supports appending, rewinding, and pruning.

Required Methods

fn append( self, item: &Self::Item, ) -> impl Future<Output = Result<(Self, u64), Error>> + Send

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

Positions are consecutively increasing starting from 0. The position of each item is stable across pruning (i.e., if item X has position 5, it will always have position 5 even if earlier items are pruned).

Errors

Returns an error if the underlying storage operation fails or if the item cannot be encoded.

fn append_many( self, items: Many<'_, Self::Item>, ) -> impl Future<Output = Result<(Self, u64), Error>> + Send

where Self::Item: Sync,

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

Returns Error::EmptyAppend if items is empty.

fn prune( self, min_position: u64, ) -> impl Future<Output = Result<(Self, bool), Error>> + Send

Prune items at positions strictly less than min_position.

Returns true if any data was pruned, false otherwise.

Behavior

• If min_position > bounds.end, the prune is capped to bounds.end (no error is returned)
• Some items with positions less than min_position may be retained due to section/blob alignment
• This operation is not atomic, but implementations guarantee the journal is left in a recoverable state if a crash occurs during pruning

Errors

Returns an error if the underlying storage operation fails.

fn rewind(self, size: u64) -> impl Future<Output = Result<Self, Error>> + Send

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

After rewinding to size N, the journal will contain exactly N items (positions 0 to N-1), and the next append will receive position N.

Behavior

• If size > bounds.end, returns Error::InvalidRewind
• If size == bounds.end, this is a no-op
• If size < bounds.start, returns Error::ItemPruned (can’t rewind to pruned data)
• This operation is not atomic, but implementations guarantee the journal is left in a recoverable state if a crash occurs during rewinding

Warnings

• This operation is not guaranteed to survive restarts until the next commit or sync completes.

Errors

Returns Error::InvalidRewind if size is beyond the current size, or Error::ItemPruned if it precedes the pruning boundary. Returns an error if the underlying storage operation fails.

fn start_sync( self, ) -> impl Future<Output = Result<(Self, Handle<()>), Error>> + Send

Begin durably persisting the current state of the journal.

Awaiting the returned Handle provides the same durability guarantee as Self::commit for the state present when the call begins (later appends need their own sync). Also tries to advance the recovery watermark to the previous proven durable size, bounding startup recovery. Use Self::sync to guarantee no recovery is needed.

fn commit(self) -> impl Future<Output = Result<Self, Error>> + Send

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

For a stronger guarantee that eliminates potential recovery, use Self::sync instead.

fn sync(self) -> impl Future<Output = Result<Self, Error>> + Send

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

This provides a stronger guarantee than Self::commit but may be slower.

fn destroy(self) -> impl Future<Output = Result<(), Error>> + Send

Destroy the journal, removing all associated storage.

This method consumes the journal and deletes all persisted data, leaving behind no storage artifacts. This can be used to clean up disk resources in tests.

Crash Safety

This operation is intended for final teardown and is not crash-safe. If interrupted, reopening the same storage may observe partially removed state. Use a reset operation provided by the concrete type when the journal must remain recoverable.

Provided Methods

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.

Warnings

• This operation is not guaranteed to survive restarts until the next commit or sync completes.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl<E: Context, A: CodecFixedShared> Mutable for commonware_storage::journal::contiguous::fixed::Journal<E, A>

impl<E: Context, V: CodecShared> Mutable for commonware_storage::journal::contiguous::variable::Journal<E, V>

impl<F, E, C, H, S> Mutable for commonware_storage::journal::authenticated::Journal<F, E, C, H, S>

where F: Family, E: Context, C: Mutable<Item: EncodeShared>, H: Hasher, S: Strategy,