ic_storage/lib.rs
1//! Scoped scalar-vector operations for an already valid live allocation.
2//!
3//! Native collection APIs neither open retained bytes nor establish allocator custody.
4//! The vector caller owns admission, initialization, publication and failure policy.
5//! The optional `map` feature adds an allocator-owned scalar hash table with
6//! scoped access, host poisoning and portable recovery. No private Vec header
7//! is admitted for persistence. The installed provider uses the vector API.
8//! The optional `checkpoint` feature supplies byte-defined bounded records and
9//! pages over caller-owned backing memory, independently of native admission.
10#![no_std]
11#![forbid(unsafe_code)]
12
13extern crate alloc;
14
15pub mod record;
16
17/// Byte-defined checkpoint storage over explicitly owned backing memory.
18#[cfg(feature = "checkpoint")]
19pub mod checkpoint;
20
21/// Native scalar hash tables, scoped mutation and portable recovery.
22#[cfg(feature = "map")]
23pub mod map;
24
25/// Ordered bounded byte keys and values with scoped access and portable recovery.
26#[cfg(feature = "ordered")]
27pub mod ordered;
28
29/// Declare a bounded scalar record; this does not grant persistence admission.
30///
31/// Requires `repr(C)`, `Copy`, one to sixteen u32/u64 fields, explicit nonzero
32/// field IDs, an eight-byte non-NUL ASCII schema ID and a nonzero version.
33/// Primitive types may use bare names or absolute `::core::primitive` paths.
34/// The optional validator checks logical encoding and decoding; `store_with`
35/// assumes an already valid record. Callers own admission and poison/trap policy.
36///
37/// ```
38/// use ic_storage::Store;
39/// #[repr(C)]
40/// #[derive(Clone, Copy, Store)]
41/// #[store(id = "APPVALUE", version = 1)]
42/// struct Value { #[store(field = 1)] count: ::core::primitive::u32 }
43/// let mut value = Value { count: 42 };
44/// assert_eq!(value.store_encode().unwrap(), [42, 0, 0, 0]);
45/// assert_eq!(Value::store_decode(&[42, 0, 0, 0]).unwrap().count, 42);
46/// assert_eq!(value.store_with(|view| view.count()), 42);
47/// ```
48///
49/// Borrowed fields refuse even if their record is Copy:
50/// ```compile_fail
51/// use ic_storage::Store;
52/// #[repr(C)]
53/// #[derive(Clone, Copy, Store)]
54/// #[store(id = "BADBORRO", version = 1)]
55/// struct Bad { #[store(field = 1)] value: &'static u64 }
56/// ```
57/// Owning fields are outside the admitted subset:
58/// ```compile_fail
59/// use ic_storage::Store;
60/// #[repr(C)]
61/// #[derive(Clone, Store)]
62/// #[store(id = "BADOWNER", version = 1)]
63/// struct Bad { #[store(field = 1)] values: Vec<u64> }
64/// ```
65/// Application Drop cannot bypass the generated Copy requirement:
66/// ```compile_fail
67/// use ic_storage::Store;
68/// #[repr(C)]
69/// #[derive(Clone, Store)]
70/// #[store(id = "BADDROPP", version = 1)]
71/// struct Bad { #[store(field = 1)] value: u64 }
72/// impl Drop for Bad { fn drop(&mut self) {} }
73/// ```
74/// Shadowing a scalar name cannot conceal a reference or a different width:
75/// ```compile_fail
76/// use ic_storage::Store;
77/// type u64 = &'static str;
78/// #[repr(C)]
79/// #[derive(Clone, Copy, Store)]
80/// #[store(id = "BADALIAS", version = 1)]
81/// struct Bad { #[store(field = 1)] value: u64 }
82/// ```
83/// ```compile_fail
84/// use ic_storage::Store;
85/// type u32 = u64;
86/// #[repr(C)]
87/// #[derive(Clone, Copy, Store)]
88/// #[store(id = "BADWIDTH", version = 1)]
89/// struct Bad { #[store(field = 1)] value: u32 }
90/// ```
91///
92/// Views cannot escape by return, outer capture or future:
93/// ```compile_fail
94/// use ic_storage::Store;
95/// #[repr(C)]
96/// #[derive(Clone, Copy, Store)]
97/// #[store(id = "APPVALUE", version = 1)]
98/// struct Value { #[store(field = 1)] count: u32 }
99/// let mut value = Value { count: 42 };
100/// let escaped = value.store_with(|view| view);
101/// ```
102/// ```compile_fail
103/// use ic_storage::Store;
104/// #[repr(C)]
105/// #[derive(Clone, Copy, Store)]
106/// #[store(id = "APPVALUE", version = 1)]
107/// struct Value { #[store(field = 1)] count: u32 }
108/// let mut value = Value { count: 42 };
109/// let mut escaped = None;
110/// value.store_with(|view| escaped = Some(view));
111/// ```
112/// ```compile_fail
113/// use ic_storage::Store;
114/// #[repr(C)]
115/// #[derive(Clone, Copy, Store)]
116/// #[store(id = "APPVALUE", version = 1)]
117/// struct Value { #[store(field = 1)] count: u32 }
118/// let mut value = Value { count: 42 };
119/// let future = value.store_with(|view| async move { view.count() });
120/// ```
121/// The view has no DerefMut route around reviewed application mutations:
122/// ```compile_fail
123/// use ic_storage::Store;
124/// #[repr(C)]
125/// #[derive(Clone, Copy, Store)]
126/// #[store(id = "APPVALUE", version = 1)]
127/// struct Value { #[store(field = 1)] count: u32 }
128/// let mut value = Value { count: 42 };
129/// value.store_with(|mut view| { let _: &mut Value = &mut *view; });
130/// ```
131#[cfg(feature = "derive")]
132pub use ic_storage_derive::Store;
133
134use alloc::vec::Vec;
135use core::alloc::Allocator;
136
137/// Expected refusal before this operation changes the logical vector.
138#[derive(Clone, Copy, Debug, PartialEq, Eq)]
139pub enum Refusal {
140 /// Initial length or an attempted append exceeds the caller's element limit.
141 Limit,
142 /// The allocator refused an append; previous values remain intact.
143 Allocation,
144}
145
146/// Lend a restricted view while keeping the owning Vec with the caller.
147///
148/// An oversized initial vector refuses before invoking the callback. Ordinary
149/// returned errors preserve preceding writes. This is not a transaction or a
150/// persistence admission API. A native host must arrange its own poisoning
151/// before invoking user code; IC callers must trap on unexpected failure.
152/// Forgetting the view does not leak the vector or leave an ownership ticket.
153///
154/// ```
155/// use ic_storage::with_vector;
156/// let mut values = vec![17, 23];
157/// let sum = with_vector(&mut values, 512, |mut view| {
158/// view.push(41).unwrap();
159/// view.values().iter().sum::<u64>()
160/// }).unwrap();
161/// assert_eq!(sum, 81);
162/// ```
163///
164/// A view cannot escape through a return value:
165/// ```compile_fail
166/// use ic_storage::with_vector;
167/// let mut values = vec![17];
168/// let escaped = with_vector(&mut values, 512, |view| view);
169/// ```
170/// An outer capture cannot retain it either:
171/// ```compile_fail
172/// use ic_storage::with_vector;
173/// let mut values = vec![17];
174/// let mut escaped = None;
175/// with_vector(&mut values, 512, |view| escaped = Some(view));
176/// ```
177/// Nor can a future carry it out of the scope:
178/// ```compile_fail
179/// use ic_storage::with_vector;
180/// let mut values = vec![17];
181/// let future = with_vector(&mut values, 512, |view| async move { view.values().len() });
182/// ```
183#[inline(always)]
184pub fn with_vector<A: Allocator, R>(
185 values: &mut Vec<u64, A>,
186 limit: usize,
187 operation: impl for<'scope> FnOnce(Vector<'scope, A>) -> R,
188) -> Result<R, Refusal> {
189 if values.len() > limit {
190 return Err(Refusal::Limit);
191 }
192 Ok(operation(Vector { values, limit }))
193}
194
195/// An exclusive scalar view, with no Deref, Clone or owning iterator.
196///
197/// Scalar slices cannot expose the Vec carrier to mem::take or mem::replace:
198/// ```compile_fail
199/// use ic_storage::with_vector;
200/// let mut values = vec![17];
201/// with_vector(&mut values, 512, |mut view| {
202/// let _: Vec<u64> = core::mem::take(view.values_mut());
203/// });
204/// ```
205/// ```compile_fail
206/// use ic_storage::with_vector;
207/// let mut values = vec![17];
208/// with_vector(&mut values, 512, |mut view| {
209/// let _ = core::mem::replace(view.values_mut(), Vec::<u64>::new());
210/// });
211/// ```
212/// Borrowed elements cannot escape:
213/// ```compile_fail
214/// use ic_storage::with_vector;
215/// let mut values = vec![17];
216/// let escaped = with_vector(&mut values, 512, |view| view.values());
217/// ```
218/// Consuming iteration cannot extract the carrier:
219/// ```compile_fail
220/// use ic_storage::with_vector;
221/// let mut values = vec![17];
222/// with_vector(&mut values, 512, |view| view.into_iter());
223/// ```
224/// The view cannot clone an owning carrier:
225/// ```compile_fail
226/// use ic_storage::with_vector;
227/// let mut values = vec![17];
228/// with_vector(&mut values, 512, |view| view.clone());
229/// ```
230pub struct Vector<'scope, A: Allocator> {
231 values: &'scope mut Vec<u64, A>,
232 limit: usize,
233}
234
235impl<A: Allocator> Vector<'_, A> {
236 /// Borrow only initialized scalar values, never spare capacity or the owner.
237 #[must_use]
238 #[inline(always)]
239 pub fn values(&self) -> &[u64] {
240 self.values
241 }
242
243 /// Mutate non-owning scalar elements without changing vector ownership.
244 #[inline(always)]
245 pub fn values_mut(&mut self) -> &mut [u64] {
246 self.values
247 }
248
249 /// Append one scalar after checking the logical limit and reserving space.
250 #[inline(always)]
251 pub fn push(&mut self, value: u64) -> Result<(), Refusal> {
252 if self.values.len() == self.limit {
253 return Err(Refusal::Limit);
254 }
255 self.values
256 .try_reserve_exact(1)
257 .map_err(|_| Refusal::Allocation)?;
258 self.values.push(value);
259 Ok(())
260 }
261
262 /// Remove the first scalar, preserving the order of remaining values.
263 #[inline(always)]
264 pub fn remove_first(&mut self) -> Option<u64> {
265 if self.values.is_empty() {
266 None
267 } else {
268 Some(self.values.remove(0))
269 }
270 }
271
272 /// Ask the existing allocator to reduce spare capacity; no platform-page claim.
273 #[inline(always)]
274 pub fn shrink_to_fit(&mut self) {
275 self.values.shrink_to_fit();
276 }
277
278 /// Remove all scalar elements while keeping the allocation available for reuse.
279 #[inline(always)]
280 pub fn clear(&mut self) {
281 self.values.clear();
282 }
283}
284
285#[cfg(test)]
286mod tests;