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 merkle;
17    pub use merkle::{mmb, mmr};
18});
19commonware_macros::stability_scope!(ALPHA, cfg(feature = "std") {
20    mod bitmap;
21    pub mod qmdb;
22    pub use crate::bitmap::{BitMap as AuthenticatedBitMap, MerkleizedBitMap, UnmerkleizedBitMap};
23    pub mod bmt;
24    pub mod cache;
25    pub mod queue;
26});
27commonware_macros::stability_scope!(BETA, cfg(feature = "std") {
28    pub mod archive;
29    pub mod freezer;
30    pub mod index;
31    pub mod journal;
32    pub mod metadata;
33    pub mod ordinal;
34    pub mod rmap;
35
36    /// A runtime context providing storage, timing, and metrics capabilities.
37    ///
38    /// This is a convenience alias for the trait bound
39    /// `Storage + Clock + Metrics` that appears on nearly every type in this crate.
40    pub trait Context:
41        commonware_runtime::Storage + commonware_runtime::Clock + commonware_runtime::Metrics
42    {
43    }
44    impl<
45            T: commonware_runtime::Storage + commonware_runtime::Clock + commonware_runtime::Metrics,
46        > Context for T
47    {
48    }
49
50    /// A storage structure with capabilities to persist and recover state across restarts.
51    pub trait Persistable {
52        /// The error type returned when there is a failure from the underlying storage system.
53        type Error;
54
55        /// Durably persist the structure, guaranteeing the current state will survive a crash.
56        ///
57        /// For a stronger guarantee that eliminates potential recovery, use [Self::sync] instead.
58        fn commit(&self) -> impl std::future::Future<Output = Result<(), Self::Error>> + Send {
59            self.sync()
60        }
61
62        /// Durably persist the structure, guaranteeing the current state will survive a crash, and that
63        /// no recovery will be needed on startup.
64        ///
65        /// This provides a stronger guarantee than [Self::commit] but may be slower.
66        fn sync(&self) -> impl std::future::Future<Output = Result<(), Self::Error>> + Send;
67
68        /// Destroy the structure, removing all associated storage.
69        ///
70        /// This method consumes the structure and deletes all persisted data, leaving behind no storage
71        /// artifacts. This can be used to clean up disk resources in tests.
72        fn destroy(self) -> impl std::future::Future<Output = Result<(), Self::Error>> + Send;
73    }
74});
75commonware_macros::stability_scope!(BETA {
76    pub mod translator;
77});
commonware_storage/lib.rs

commonware_storage/
lib.rs
