ic_storage/
adapter.rs

1//! Supported upstream collections with governed memory and an explicit API.
2//!
3//! Constructors preserve upstream initialization, panic and persisted-format
4//! contracts. Mutations are not our custom tree's staged transactions. These
5//! wrappers expose neither raw memory nor unrestricted upstream collections.
6//! Use distinct admitted allocations, drop before reopening, and never retain
7//! memory clones. IC Memory 0.45 does not yet enforce exclusive allocation leases.
8use crate::substrate::{self, DefaultMemoryImpl, Memory};
9pub use crate::{BTreeMap, Comparator, Config, Entry, Error, Lexicographic, Range};
10use ic_memory::RuntimeMemory;
11use std::ops::RangeBounds;
12pub use substrate::{Storable, storable};
13
14/// Governed upstream `BTreeMap`; initialization and failures follow upstream contracts.
15pub struct StableBTreeMap<K: Storable + Ord + Clone, V: Storable, M: Memory = DefaultMemoryImpl> {
16    inner: substrate::BTreeMap<K, V, RuntimeMemory<M>>,
17}
18impl<K: Storable + Ord + Clone, V: Storable, M: Memory> StableBTreeMap<K, V, M> {
19    /// Delegates to upstream `BTreeMap::new` with the governed allocation.
20    pub fn new(memory: RuntimeMemory<M>) -> Self {
21        Self {
22            inner: substrate::BTreeMap::new(memory),
23        }
24    }
25    /// Delegates to upstream `BTreeMap::init` with the governed allocation.
26    pub fn init(memory: RuntimeMemory<M>) -> Self {
27        Self {
28            inner: substrate::BTreeMap::init(memory),
29        }
30    }
31    /// Delegates to upstream `BTreeMap::load` with the governed allocation.
32    pub fn load(memory: RuntimeMemory<M>) -> Self {
33        Self {
34            inner: substrate::BTreeMap::load(memory),
35        }
36    }
37    /// Delegates to upstream `BTreeMap::insert` with the governed allocation.
38    pub fn insert(&mut self, key: K, value: V) -> Option<V> {
39        self.inner.insert(key, value)
40    }
41    /// Delegates to upstream `BTreeMap::get` with the governed allocation.
42    pub fn get(&self, key: &K) -> Option<V> {
43        self.inner.get(key)
44    }
45    /// Delegates to upstream `BTreeMap::contains_key` with the governed allocation.
46    pub fn contains_key(&self, key: &K) -> bool {
47        self.inner.contains_key(key)
48    }
49    /// Delegates to upstream `BTreeMap::is_empty` with the governed allocation.
50    pub fn is_empty(&self) -> bool {
51        self.inner.is_empty()
52    }
53    /// Delegates to upstream `BTreeMap::len` with the governed allocation.
54    pub fn len(&self) -> u64 {
55        self.inner.len()
56    }
57    /// Delegates to upstream `BTreeMap::remove` with the governed allocation.
58    pub fn remove(&mut self, key: &K) -> Option<V> {
59        self.inner.remove(key)
60    }
61    /// Delegates to upstream `BTreeMap::first_key_value` with the governed allocation.
62    pub fn first_key_value(&self) -> Option<(K, V)> {
63        self.inner.first_key_value()
64    }
65    /// Delegates to upstream `BTreeMap::last_key_value` with the governed allocation.
66    pub fn last_key_value(&self) -> Option<(K, V)> {
67        self.inner.last_key_value()
68    }
69    /// Delegates to upstream `BTreeMap::pop_first` with the governed allocation.
70    pub fn pop_first(&mut self) -> Option<(K, V)> {
71        self.inner.pop_first()
72    }
73    /// Delegates to upstream `BTreeMap::pop_last` with the governed allocation.
74    pub fn pop_last(&mut self) -> Option<(K, V)> {
75        self.inner.pop_last()
76    }
77    /// Delegates to upstream `BTreeMap::iter` with the governed allocation.
78    pub fn iter(&self) -> MapIter<'_, K, V, M> {
79        self.inner.iter()
80    }
81    /// Delegates to upstream `BTreeMap::range` with the governed allocation.
82    pub fn range(&self, key_range: impl RangeBounds<K>) -> MapIter<'_, K, V, M> {
83        self.inner.range(key_range)
84    }
85    /// Delegates to upstream `BTreeMap::keys` with the governed allocation.
86    pub fn keys(&self) -> impl DoubleEndedIterator<Item = K> + '_ {
87        self.inner.keys()
88    }
89    /// Delegates to upstream `BTreeMap::values` with the governed allocation.
90    pub fn values(&self) -> impl DoubleEndedIterator<Item = V> + '_ {
91        self.inner.values()
92    }
93}
94
95/// Governed upstream `BTreeSet`; initialization and failures follow upstream contracts.
96pub struct StableBTreeSet<K: Storable + Ord + Clone, M: Memory = DefaultMemoryImpl> {
97    inner: substrate::BTreeSet<K, RuntimeMemory<M>>,
98}
99impl<K: Storable + Ord + Clone, M: Memory> StableBTreeSet<K, M> {
100    /// Delegates to upstream `BTreeSet::new` with the governed allocation.
101    pub fn new(memory: RuntimeMemory<M>) -> Self {
102        Self {
103            inner: substrate::BTreeSet::new(memory),
104        }
105    }
106    /// Delegates to upstream `BTreeSet::init` with the governed allocation.
107    pub fn init(memory: RuntimeMemory<M>) -> Self {
108        Self {
109            inner: substrate::BTreeSet::init(memory),
110        }
111    }
112    /// Delegates to upstream `BTreeSet::load` with the governed allocation.
113    pub fn load(memory: RuntimeMemory<M>) -> Self {
114        Self {
115            inner: substrate::BTreeSet::load(memory),
116        }
117    }
118    /// Delegates to upstream `BTreeSet::insert` with the governed allocation.
119    pub fn insert(&mut self, key: K) -> bool {
120        self.inner.insert(key)
121    }
122    /// Delegates to upstream `BTreeSet::contains` with the governed allocation.
123    pub fn contains(&self, key: &K) -> bool {
124        self.inner.contains(key)
125    }
126    /// Delegates to upstream `BTreeSet::is_empty` with the governed allocation.
127    pub fn is_empty(&self) -> bool {
128        self.inner.is_empty()
129    }
130    /// Delegates to upstream `BTreeSet::len` with the governed allocation.
131    pub fn len(&self) -> u64 {
132        self.inner.len()
133    }
134    /// Delegates to upstream `BTreeSet::remove` with the governed allocation.
135    pub fn remove(&mut self, key: &K) -> bool {
136        self.inner.remove(key)
137    }
138    /// Delegates to upstream `BTreeSet::first` with the governed allocation.
139    pub fn first(&self) -> Option<K> {
140        self.inner.first()
141    }
142    /// Delegates to upstream `BTreeSet::last` with the governed allocation.
143    pub fn last(&self) -> Option<K> {
144        self.inner.last()
145    }
146    /// Delegates to upstream `BTreeSet::pop_first` with the governed allocation.
147    pub fn pop_first(&mut self) -> Option<K> {
148        self.inner.pop_first()
149    }
150    /// Delegates to upstream `BTreeSet::pop_last` with the governed allocation.
151    pub fn pop_last(&mut self) -> Option<K> {
152        self.inner.pop_last()
153    }
154    /// Delegates to upstream `BTreeSet::iter` with the governed allocation.
155    pub fn iter(&self) -> SetIter<'_, K, M> {
156        self.inner.iter()
157    }
158    /// Delegates to upstream `BTreeSet::range` with the governed allocation.
159    pub fn range(&self, key_range: impl RangeBounds<K>) -> SetIter<'_, K, M> {
160        self.inner.range(key_range)
161    }
162    /// Delegates to upstream `BTreeSet::clear` with the governed allocation.
163    pub fn clear(&mut self) {
164        self.inner.clear();
165    }
166}
167
168/// Governed upstream `Cell`; initialization and failures follow upstream contracts.
169pub struct StableCell<T: Storable, M: Memory = DefaultMemoryImpl> {
170    inner: substrate::Cell<T, RuntimeMemory<M>>,
171}
172impl<T: Storable, M: Memory> StableCell<T, M> {
173    /// Delegates to upstream `Cell::new` with the governed allocation.
174    pub fn new(memory: RuntimeMemory<M>, value: T) -> Self {
175        Self {
176            inner: substrate::Cell::new(memory, value),
177        }
178    }
179    /// Delegates to upstream `Cell::init` with the governed allocation.
180    pub fn init(memory: RuntimeMemory<M>, default_value: T) -> Self {
181        Self {
182            inner: substrate::Cell::init(memory, default_value),
183        }
184    }
185    /// Delegates to upstream `Cell::get` with the governed allocation.
186    pub fn get(&self) -> &T {
187        self.inner.get()
188    }
189    /// Delegates to upstream `Cell::set` with the governed allocation.
190    pub fn set(&mut self, value: T) -> T {
191        self.inner.set(value)
192    }
193}
194
195/// Governed upstream `Vec`; initialization and failures follow upstream contracts.
196pub struct StableVec<T: Storable, M: Memory = DefaultMemoryImpl> {
197    inner: substrate::Vec<T, RuntimeMemory<M>>,
198}
199impl<T: Storable, M: Memory> StableVec<T, M> {
200    /// Delegates to upstream `Vec::new` with the governed allocation.
201    pub fn new(memory: RuntimeMemory<M>) -> Self {
202        Self {
203            inner: substrate::Vec::new(memory),
204        }
205    }
206    /// Delegates to upstream `Vec::init` with the governed allocation.
207    pub fn init(memory: RuntimeMemory<M>) -> Self {
208        Self {
209            inner: substrate::Vec::init(memory),
210        }
211    }
212    /// Delegates to upstream `Vec::get` with the governed allocation.
213    pub fn get(&self, index: u64) -> Option<T> {
214        self.inner.get(index)
215    }
216    /// Delegates to upstream `Vec::set` with the governed allocation.
217    pub fn set(&self, index: u64, item: &T) {
218        self.inner.set(index, item);
219    }
220    /// Delegates to upstream `Vec::push` with the governed allocation.
221    pub fn push(&self, item: &T) {
222        self.inner.push(item);
223    }
224    /// Delegates to upstream `Vec::pop` with the governed allocation.
225    pub fn pop(&self) -> Option<T> {
226        self.inner.pop()
227    }
228    /// Delegates to upstream `Vec::len` with the governed allocation.
229    pub fn len(&self) -> u64 {
230        self.inner.len()
231    }
232    /// Delegates to upstream `Vec::is_empty` with the governed allocation.
233    pub fn is_empty(&self) -> bool {
234        self.inner.is_empty()
235    }
236    /// Delegates to upstream `Vec::iter` with the governed allocation.
237    pub fn iter(&self) -> impl DoubleEndedIterator<Item = T> + '_ {
238        self.inner.iter()
239    }
240}
241
242/// Governed upstream `MinHeap`; initialization and failures follow upstream contracts.
243pub struct StableMinHeap<T: Storable + Ord, M: Memory = DefaultMemoryImpl> {
244    inner: substrate::MinHeap<T, RuntimeMemory<M>>,
245}
246impl<T: Storable + Ord, M: Memory> StableMinHeap<T, M> {
247    /// Delegates to upstream `MinHeap::new` with the governed allocation.
248    pub fn new(memory: RuntimeMemory<M>) -> Self {
249        Self {
250            inner: substrate::MinHeap::new(memory),
251        }
252    }
253    /// Delegates to upstream `MinHeap::init` with the governed allocation.
254    pub fn init(memory: RuntimeMemory<M>) -> Self {
255        Self {
256            inner: substrate::MinHeap::init(memory),
257        }
258    }
259    /// Delegates to upstream `MinHeap::push` with the governed allocation.
260    pub fn push(&mut self, item: &T) {
261        self.inner.push(item);
262    }
263    /// Delegates to upstream `MinHeap::pop` with the governed allocation.
264    pub fn pop(&mut self) -> Option<T> {
265        self.inner.pop()
266    }
267    /// Delegates to upstream `MinHeap::peek` with the governed allocation.
268    pub fn peek(&self) -> Option<T> {
269        self.inner.peek()
270    }
271    /// Delegates to upstream `MinHeap::len` with the governed allocation.
272    pub fn len(&self) -> u64 {
273        self.inner.len()
274    }
275    /// Delegates to upstream `MinHeap::is_empty` with the governed allocation.
276    pub fn is_empty(&self) -> bool {
277        self.inner.is_empty()
278    }
279    /// Delegates to upstream `MinHeap::iter` with the governed allocation.
280    pub fn iter(&self) -> impl Iterator<Item = T> + '_ {
281        self.inner.iter()
282    }
283}
284
285/// Governed upstream `Log`; initialization and failures follow upstream contracts.
286pub struct StableLog<T: Storable, M: Memory = DefaultMemoryImpl> {
287    inner: substrate::Log<T, RuntimeMemory<M>, RuntimeMemory<M>>,
288}
289impl<T: Storable, M: Memory> StableLog<T, M> {
290    /// Delegates to upstream `Log::new` with the governed allocation.
291    pub fn new(index_memory: RuntimeMemory<M>, data_memory: RuntimeMemory<M>) -> Self {
292        Self {
293            inner: substrate::Log::new(index_memory, data_memory),
294        }
295    }
296    /// Delegates to upstream `Log::init` with the governed allocation.
297    pub fn init(index_memory: RuntimeMemory<M>, data_memory: RuntimeMemory<M>) -> Self {
298        Self {
299            inner: substrate::Log::init(index_memory, data_memory),
300        }
301    }
302    /// Delegates to upstream `Log::first` with the governed allocation.
303    pub fn first(&self) -> Option<T> {
304        self.inner.first()
305    }
306    /// Delegates to upstream `Log::last` with the governed allocation.
307    pub fn last(&self) -> Option<T> {
308        self.inner.last()
309    }
310    /// Delegates to upstream `Log::get` with the governed allocation.
311    pub fn get(&self, idx: u64) -> Option<T> {
312        self.inner.get(idx)
313    }
314    /// Delegates to upstream `Log::len` with the governed allocation.
315    pub fn len(&self) -> u64 {
316        self.inner.len()
317    }
318    /// Delegates to upstream `Log::is_empty` with the governed allocation.
319    pub fn is_empty(&self) -> bool {
320        self.inner.is_empty()
321    }
322    /// Delegates to upstream `Log::append` with the governed allocation.
323    /// # Errors
324    /// Returns the upstream write error if memory cannot grow.
325    pub fn append(&self, item: &T) -> Result<u64, LogWriteError> {
326        self.inner.append(item)
327    }
328    /// Delegates to upstream `Log::iter` with the governed allocation.
329    pub fn iter(&self) -> LogIter<'_, T, M> {
330        self.inner.iter()
331    }
332}
333
334/// Upstream map iterator with governed memory.
335pub type MapIter<'a, K, V, M = DefaultMemoryImpl> =
336    substrate::btreemap::Iter<'a, K, V, RuntimeMemory<M>>;
337/// Upstream set iterator with governed memory.
338pub type SetIter<'a, K, M = DefaultMemoryImpl> = substrate::btreeset::Iter<'a, K, RuntimeMemory<M>>;
339/// Upstream log iterator with governed index and data memories.
340pub type LogIter<'a, T, M = DefaultMemoryImpl> =
341    substrate::log::Iter<'a, T, RuntimeMemory<M>, RuntimeMemory<M>>;
342
343pub use substrate::cell::{InitError as CellInitError, ValueError as CellValueError};
344pub use substrate::log::{InitError as LogInitError, NoSuchEntry, WriteError as LogWriteError};
345pub use substrate::vec::InitError as VecInitError;
346
347impl<'a, K: Storable + Ord + Clone, V: Storable, M: Memory> IntoIterator
348    for &'a StableBTreeMap<K, V, M>
349{
350    type Item = <MapIter<'a, K, V, M> as Iterator>::Item;
351    type IntoIter = MapIter<'a, K, V, M>;
352    fn into_iter(self) -> Self::IntoIter {
353        self.iter()
354    }
355}
356
357impl<'a, K: Storable + Ord + Clone, M: Memory> IntoIterator for &'a StableBTreeSet<K, M> {
358    type Item = K;
359    type IntoIter = SetIter<'a, K, M>;
360    fn into_iter(self) -> Self::IntoIter {
361        self.iter()
362    }
363}
364
365impl<'a, T: Storable, M: Memory> IntoIterator for &'a StableLog<T, M> {
366    type Item = T;
367    type IntoIter = LogIter<'a, T, M>;
368    fn into_iter(self) -> Self::IntoIter {
369        self.iter()
370    }
371}
ic_storage/adapter.rs

ic_storage/
adapter.rs
