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 bmt;
17    pub mod merkle;
18    pub use merkle::{mmb, mmr};
19});
20commonware_macros::stability_scope!(ALPHA, cfg(feature = "std") {
21    mod bitmap;
22    pub mod qmdb;
23    pub use crate::bitmap::{BitMap as AuthenticatedBitMap, MerkleizedBitMap, UnmerkleizedBitMap};
24    pub mod cache;
25    pub mod queue;
26    #[cfg(any(test, feature = "test-utils"))]
27    pub mod utils;
28});
29commonware_macros::stability_scope!(BETA, cfg(feature = "std") {
30    /// A shared in-flight sync result. Detached observers of the same completion: dropping one
31    /// neither cancels the sync nor consumes its result.
32    pub(crate) type SyncCompletion = futures::future::Shared<
33        futures::future::BoxFuture<'static, Result<(), commonware_runtime::Error>>,
34    >;
35
36    pub mod archive;
37    pub mod freezer;
38    pub mod index;
39    pub mod journal;
40    pub mod metadata;
41    pub mod ordinal;
42    pub mod rmap;
43
44    /// Section selector for storage operations that act on one or more sections.
45    pub trait Sections {
46        /// Iterator over selected sections.
47        type Iter: Iterator<Item = u64>;
48
49        /// Convert into selected section indices.
50        ///
51        /// This trait does not impose ordering or uniqueness; each storage operation decides how
52        /// to handle duplicates and missing sections.
53        fn sections(self) -> Self::Iter;
54    }
55
56    impl Sections for u64 {
57        type Iter = core::iter::Once<Self>;
58
59        fn sections(self) -> Self::Iter {
60            core::iter::once(self)
61        }
62    }
63
64    impl<const N: usize> Sections for [u64; N] {
65        type Iter = core::array::IntoIter<u64, N>;
66
67        fn sections(self) -> Self::Iter {
68            self.into_iter()
69        }
70    }
71
72    impl<'a, const N: usize> Sections for &'a [u64; N] {
73        type Iter = core::iter::Copied<core::slice::Iter<'a, u64>>;
74
75        fn sections(self) -> Self::Iter {
76            self.iter().copied()
77        }
78    }
79
80    impl<'a> Sections for &'a [u64] {
81        type Iter = core::iter::Copied<core::slice::Iter<'a, u64>>;
82
83        fn sections(self) -> Self::Iter {
84            self.iter().copied()
85        }
86    }
87
88    impl Sections for Vec<u64> {
89        type Iter = std::vec::IntoIter<u64>;
90
91        fn sections(self) -> Self::Iter {
92            self.into_iter()
93        }
94    }
95
96    impl<'a> Sections for &'a Vec<u64> {
97        type Iter = core::iter::Copied<core::slice::Iter<'a, u64>>;
98
99        fn sections(self) -> Self::Iter {
100            self.iter().copied()
101        }
102    }
103
104    impl Sections for std::collections::BTreeSet<u64> {
105        type Iter = std::collections::btree_set::IntoIter<u64>;
106
107        fn sections(self) -> Self::Iter {
108            self.into_iter()
109        }
110    }
111
112    impl<'a> Sections for &'a std::collections::BTreeSet<u64> {
113        type Iter = core::iter::Copied<std::collections::btree_set::Iter<'a, u64>>;
114
115        fn sections(self) -> Self::Iter {
116            self.iter().copied()
117        }
118    }
119
120    /// A runtime context providing storage, timing, and metrics capabilities.
121    ///
122    /// This is a convenience alias for the trait bound `BufferPooler + Storage + Clock + Metrics`
123    /// that appears on nearly every type in this crate.
124    pub trait Context:
125        commonware_runtime::BufferPooler
126        + commonware_runtime::Storage
127        + commonware_runtime::Clock
128        + commonware_runtime::Metrics
129    {
130    }
131    impl<
132        T: commonware_runtime::BufferPooler
133            + commonware_runtime::Storage
134            + commonware_runtime::Clock
135            + commonware_runtime::Metrics,
136    > Context for T
137    {
138    }
139});
140commonware_macros::stability_scope!(BETA {
141    pub mod translator;
142});
commonware_storage/lib.rs

commonware_storage/
lib.rs
