commonware_storage/
lib.rs

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

commonware_storage/
lib.rs
