commonware_storage/
lib.rs

1//! Persist and retrieve data from an abstract store.
2//!
3//! # Status
4//!
5//! `commonware-storage` is **ALPHA** software and is not yet recommended for production use. Developers should
6//! expect breaking changes and occasional instability.
7
8#![doc(
9    html_logo_url = "https://commonware.xyz/imgs/rustdoc_logo.svg",
10    html_favicon_url = "https://commonware.xyz/favicon.ico"
11)]
12#![cfg_attr(not(feature = "std"), no_std)]
13
14extern crate alloc;
15pub mod mmr;
16
17cfg_if::cfg_if! {
18    if #[cfg(feature = "std")] {
19        pub mod qmdb;
20        pub mod archive;
21        mod bitmap;
22        pub use bitmap::{BitMap as AuthenticatedBitMap, CleanBitMap as CleanAuthenticatedBitMap, DirtyBitMap as DirtyAuthenticatedBitMap};
23        pub mod bmt;
24        pub mod cache;
25        pub mod freezer;
26        pub mod index;
27        pub mod journal;
28        pub mod kv;
29        pub mod metadata;
30        pub mod ordinal;
31        pub mod rmap;
32        pub mod translator;
33    }
34}
35
36/// A storage structure with capabilities to persist and recover state across restarts.
37#[cfg(feature = "std")]
38pub trait Persistable {
39    /// The error type returned when there is a failure from the underlying storage system.
40    type Error;
41
42    /// Durably persist the structure, guaranteeing the current state will survive a crash.
43    ///
44    /// For a stronger guarantee that eliminates potential recovery, use [Self::sync] instead.
45    fn commit(&mut self) -> impl std::future::Future<Output = Result<(), Self::Error>> + Send {
46        self.sync()
47    }
48
49    /// Durably persist the structure, guaranteeing the current state will survive a crash, and that
50    /// no recovery will be needed on startup.
51    ///
52    /// This provides a stronger guarantee than [Self::commit] but may be slower.
53    fn sync(&mut self) -> impl std::future::Future<Output = Result<(), Self::Error>> + Send;
54
55    /// Destroy the structure, removing all associated storage.
56    ///
57    /// This method consumes the structure and deletes all persisted data, leaving behind no storage
58    /// artifacts. This can be used to clean up disk resources in tests.
59    fn destroy(self) -> impl std::future::Future<Output = Result<(), Self::Error>> + Send;
60}
commonware_storage/lib.rs

commonware_storage/
lib.rs
