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