Struct Journal 

pub struct Journal<F, E, C, H>
where
    F: Family,
    E: Context,
    C: Contiguous<Item: EncodeShared>,
    H: Hasher,
{ /* private fields */ }

An append-only data structure that maintains a sequential journal of items alongside a Merkle-family structure. The item at index i in the journal corresponds to the leaf at Location i in the Merkle structure. This structure enables efficient proofs that an item is included in the journal at a specific location.

Implementations

impl<F, E, C, H> Journal<F, E, C, H>

where F: Family, E: Context, C: Contiguous<Item: EncodeShared>, H: Hasher,

pub async fn size(&self) -> Location<F>

Returns the Location of the next item appended to the journal.

pub fn root(&self) -> H::Digest

Return the root of the Merkle structure.

pub fn new_batch(&self) -> UnmerkleizedBatch<F, H, C::Item>

where C::Item: Encode,

Create a speculative batch atop this journal.

impl<F, E, C, H> Journal<F, E, C, H>

where F: Family, E: Context, C: Contiguous<Item: EncodeShared> + Persistable<Error = Error>, H: Hasher,

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

Durably persist the journal. This is faster than sync() but does not persist the Merkle structure, meaning recovery will be required on startup if we crash before sync().

impl<F, E, C, H> Journal<F, E, C, H>

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

pub async fn from_components( merkle: Journaled<F, E, H::Digest>, journal: C, hasher: StandardHasher<H>, apply_batch_size: u64, ) -> Result<Self, Error<F>>

Create a new Journal from the given components after aligning the Merkle structure with the journal.

pub async fn append(&mut self, item: &C::Item) -> Result<Location<F>, Error<F>>

Append an item to the journal and update the Merkle structure.

pub async fn apply_batch( &mut self, batch: &MerkleizedBatch<F, H::Digest, C::Item>, ) -> Result<(), Error<F>>

Apply a batch to the journal.

A batch is valid if the journal has not been modified since the batch chain was created, or if only ancestors of this batch have been applied. Already-committed ancestors are skipped automatically. Applying a batch from a different fork returns an error.

pub async fn prune( &mut self, prune_loc: Location<F>, ) -> Result<Location<F>, Error<F>>

Prune both the Merkle structure and journal to the given location.

Returns

The new pruning boundary, which may be less than the requested prune_loc.

impl<F, E, C, H> Journal<F, E, C, H>

where F: Family, E: Context, C: Contiguous<Item: EncodeShared>, H: Hasher,

pub async fn proof( &self, start_loc: Location<F>, max_ops: NonZeroU64, ) -> Result<(Proof<F, H::Digest>, Vec<C::Item>), Error<F>>

Generate a proof of inclusion for items starting at start_loc.

Returns a proof and the items corresponding to the leaves in the range start_loc..end_loc, where end_loc is the minimum of the current item count and start_loc + max_ops.

Errors

• Returns Error::Merkle with merkle::Error::LocationOverflow if start_loc > Family::MAX_LEAVES.
• Returns Error::Merkle with merkle::Error::RangeOutOfBounds if start_loc >= current item count.
• Returns Error::Journal with crate::journal::Error::ItemPruned if start_loc has been pruned.

pub async fn historical_proof( &self, historical_leaves: Location<F>, start_loc: Location<F>, max_ops: NonZeroU64, ) -> Result<(Proof<F, H::Digest>, Vec<C::Item>), Error<F>>

Generate a historical proof with respect to the state of the Merkle structure when it had historical_leaves leaves.

Returns a proof and the items corresponding to the leaves in the range start_loc..end_loc, where end_loc is the minimum of historical_leaves and start_loc + max_ops.

Errors

• Returns Error::Merkle with merkle::Error::RangeOutOfBounds if start_loc >= historical_leaves or historical_leaves > number of items in the journal.
• Returns Error::Journal with crate::journal::Error::ItemPruned if start_loc has been pruned.

impl<F, E, C, H> Journal<F, E, C, H>

where F: Family, E: Context, C: Contiguous<Item: EncodeShared> + Persistable<Error = Error>, H: Hasher,

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

Destroy the authenticated journal, removing all data from disk.

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

Durably persist the journal, ensuring no recovery is required on startup.

impl<F, E, O, H> Journal<F, E, Journal<E, O>, H>

where F: Family, E: Context, O: CodecFixedShared, H: Hasher,

pub async fn new( context: E, merkle_cfg: Config, journal_cfg: Config, rewind_predicate: fn(&O) -> bool, ) -> Result<Self, Error<F>>

Create a new authenticated Journal.

The inner journal will be rewound to the last item matching rewind_predicate, and the merkle structure will be aligned to match.

impl<F, E, O, H> Journal<F, E, Journal<E, O>, H>

where F: Family, E: Context, O: CodecShared, H: Hasher,

pub async fn new( context: E, merkle_cfg: Config, journal_cfg: Config<O::Cfg>, rewind_predicate: fn(&O) -> bool, ) -> Result<Self, Error<F>>

Create a new authenticated Journal.

The inner journal will be rewound to the last item matching rewind_predicate, and the merkle structure will be aligned to match.

Trait Implementations

impl<F, E, C, H> Contiguous for Journal<F, E, C, H>

where F: Family, E: Context, C: Contiguous<Item: EncodeShared>, H: Hasher,

type Item = <C as Contiguous>::Item

The type of items stored in the journal.

async fn reader(&self) -> impl Reader<Item = C::Item> + '_

Acquire a reader guard that holds a consistent view of the journal.

async fn size(&self) -> u64

Return the total number of items that have been appended to the journal.

impl<F, E, C, H> Mutable for Journal<F, E, C, H>

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

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

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

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

Prune items at positions strictly less than min_position.

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

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

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

where Self::Item: Sync,

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

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.

impl<F, E, C, H> Persistable for Journal<F, E, C, H>

where F: Family, E: Context, C: Contiguous<Item: EncodeShared> + Persistable<Error = Error>, H: Hasher,

type Error = Error

The error type returned when there is a failure from the underlying storage system.

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

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

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

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

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

Destroy the structure, removing all associated storage.