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
//! A branded write-once slot for in-place decode, and its initialization proof.
//!
//! The in-place helpers ([`Arena::emplace`](crate::Arena::emplace),
//! [`DecodeVec::emplace`](crate::DecodeVec::emplace), [`decode_value`](crate::decode_value)) hand a
//! decode closure a [`Slot`] over uninitialized storage and must then treat that storage as a live
//! `T` (publish it into a slice, return a `&mut T`, or move it out). For that to be sound **for any
//! safe closure**, the helper needs an *unforgeable* proof that the closure actually wrote the slot.
//!
//! The proof is [`Init`]: a zero-sized token carrying a brand lifetime `'id`. [`Slot::write`] is the
//! only way to obtain an `Init<'id>`, and it writes the slot. The helpers bind the closure as
//! `for<'id> FnOnce(Slot<'id, T>) -> Result<Init<'id>, E>`, so `'id` is a *fresh, invariant* brand
//! per call: the closure cannot possess an `Init<'id>` of that brand from anywhere else (a token of a
//! different brand does not coerce, and nothing but `write` constructs one). Hence an `Ok(Init)`
//! return is a compile-time proof the slot was initialized -- a leaked/foreign reference cannot stand
//! in for the token. This is the GhostToken/`generativity` branding technique.
use PhantomData;
use MaybeUninit;
use NonNull;
/// `PhantomData` that is **invariant** in `'id` (so no other lifetime, including `'static`, unifies
/// with a fresh brand).
type Brand<'id> = ;
/// A write-once handle to one uninitialized `T` slot, branded with `'id`. Obtained only from an
/// in-place helper; its sole consuming operation is [`write`](Self::write), which initializes the
/// slot and yields the matching [`Init`] proof.
/// Proof that the [`Slot`] of the same brand `'id` was written. A zero-sized token constructible only
/// by [`Slot::write`]; it cannot be forged, so a helper that receives `Init<'id>` from its closure
/// knows the branded slot is initialized.
///
/// The forge that broke the earlier `-> &mut T` witness -- a safe closure returning `Ok` without ever
/// writing the slot -- is a compile error now: there is no way to produce an `Init<'id>` of the
/// freshly-branded slot except by writing it. A closure that tries to return some *other* `Init`
/// cannot type-check, because the brand is invariant and fresh per call:
///
/// ```compile_fail
/// use rapidproto::{decode_value, Init, Slot};
/// // Try to satisfy the `Init` proof without writing the slot by smuggling in a token of another
/// // brand. The `for<'id>` bound makes the slot's brand fresh and invariant, so no outside `Init`
/// // unifies with it: this does not compile.
/// fn forge<'other>(stolen: Init<'other>) -> u64 {
/// decode_value::<u64, (), _>(|_slot: Slot<'_, u64>| Ok(stolen)).unwrap()
/// }
/// ```
/// Decode a `T` **by value** in place: run `f` against a stack slot and, on its [`Init`] proof,
/// return the now-initialized value by move. Lets generated map-value / by-value sites use the
/// branded-slot decode form while keeping all `unsafe` in the runtime. Sound for any safe `f` (the
/// `Init` proof is unforgeable); does not allocate.
///
/// `#[inline(always)]`: like the other in-place helpers ([`Arena::emplace`](crate::Arena::emplace),
/// [`DecodeVec::emplace`](crate::DecodeVec::emplace)), this must inline into the caller so the decoded
/// payload slice stays in registers rather than being pinned to memory through the closure environment
/// (an out-of-line call takes the environment's address), and so the optimizer can fold the decode in.