ic_storage/
governed.rs

1//! Public custom-tree boundary. Allocation admission is supplied by IC Memory.
2use crate::substrate::DefaultMemoryImpl;
3use crate::{Comparator, Config, Entry, Error, Lexicographic, Memory, Range, btree};
4use ic_memory::RuntimeMemory;
5use std::ops::Bound;
6
7/// Our page-based tree consuming a governed allocation handle.
8/// No raw memory access or extraction is exposed; drop before reopening.
9pub struct BTreeMap<M: Memory = DefaultMemoryImpl, C: Comparator = Lexicographic> {
10    inner: btree::BTreeMap<RuntimeMemory<M>, C>,
11}
12impl<M: Memory, C: Comparator> BTreeMap<M, C> {
13    /// Create the custom format with the exact configuration and comparator.
14    /// # Errors
15    /// Returns the engine's format, configuration, corruption or capacity error.
16    pub fn create(memory: RuntimeMemory<M>, config: Config, order: C) -> Result<Self, Error> {
17        btree::BTreeMap::create(memory, config, order).map(|inner| Self { inner })
18    }
19    /// Open the custom format with the exact configuration and comparator.
20    /// # Errors
21    /// Returns the engine's format, configuration, corruption or capacity error.
22    pub fn open(memory: RuntimeMemory<M>, config: Config, order: C) -> Result<Self, Error> {
23        btree::BTreeMap::open(memory, config, order).map(|inner| Self { inner })
24    }
25    /// Number of persisted live entries.
26    #[must_use]
27    pub fn len(&self) -> u64 {
28        self.inner.len()
29    }
30    /// Whether there are no live entries.
31    #[must_use]
32    pub fn is_empty(&self) -> bool {
33        self.inner.is_empty()
34    }
35    /// Bytes reserved, including reusable free pages.
36    #[must_use]
37    pub fn memory_bytes(&self) -> u64 {
38        self.inner.memory_bytes()
39    }
40    /// Read the value for an encoded key.
41    /// # Errors
42    /// Propagates validation, corruption and capacity errors from the engine.
43    pub fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>, Error> {
44        self.inner.get(key)
45    }
46    /// Test membership without reading external value payloads.
47    /// # Errors
48    /// Propagates validation, corruption and capacity errors from the engine.
49    pub fn contains_key(&self, key: &[u8]) -> Result<bool, Error> {
50        self.inner.contains_key(key)
51    }
52    /// Insert or replace a value, returning its previous bytes.
53    /// # Errors
54    /// Propagates validation, corruption and capacity errors from the engine.
55    pub fn insert(&mut self, key: &[u8], value: &[u8]) -> Result<Option<Vec<u8>>, Error> {
56        self.inner.insert(key, value)
57    }
58    /// Remove a key, returning its previous value.
59    /// # Errors
60    /// Propagates validation, corruption and capacity errors from the engine.
61    pub fn remove(&mut self, key: &[u8]) -> Result<Option<Vec<u8>>, Error> {
62        self.inner.remove(key)
63    }
64    /// Lazily scan comparator-ordered bounds in either direction.
65    /// # Errors
66    /// Propagates validation, corruption and capacity errors from the engine.
67    pub fn range(
68        &self,
69        lower: Bound<&[u8]>,
70        upper: Bound<&[u8]>,
71    ) -> Result<Range<'_, M, C>, Error> {
72        self.inner.range(lower, upper)
73    }
74    /// Lazily scan all entries in either direction.
75    #[must_use]
76    pub fn iter(&self) -> Range<'_, M, C> {
77        self.inner.iter()
78    }
79    /// Audit reachable pages, ordering, counts and free-list ownership.
80    /// # Errors
81    /// Propagates validation, corruption and capacity errors from the engine.
82    pub fn validate(&self) -> Result<(), Error> {
83        self.inner.validate()
84    }
85}
86impl<'a, M: Memory, C: Comparator> IntoIterator for &'a BTreeMap<M, C> {
87    type Item = Result<Entry<'a, M, C>, Error>;
88    type IntoIter = Range<'a, M, C>;
89    fn into_iter(self) -> Self::IntoIter {
90        self.iter()
91    }
92}
ic_storage/governed.rs

ic_storage/
governed.rs
