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