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

ic_storage/
adapter.rs
