rapidproto 0.1.0-alpha.2

Runtime for the Protobuf decoders that rapidproto-build generates.
Documentation
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
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
//! A decode-time growable array backed by the arena, finished into a borrowed slice.
//!
//! Generated decoders use it to gather a repeated field in a single pass: elements are pushed as they
//! are read off the wire, then [`into_slice`](DecodeVec::into_slice) hands back the finished
//! `&'a [T]`. A grow allocates a larger arena array and copies the elements over; the old array is
//! abandoned (the arena never frees, matching the C++ decoder's growable repeated storage). This is
//! the only place the growth bookkeeping lives, so the generated code stays simple.

use core::ptr::{self, NonNull};

use crate::arena::{Arena, ArenaExhausted};

mod sealed {
    pub trait Sealed {}
}

/// A fixed-width scalar whose in-memory **little-endian** byte image is exactly its protobuf
/// `fixed32`/`fixed64` wire encoding: `u32`/`i32`/`f32` (4 bytes) and `u64`/`i64`/`f64` (8 bytes).
///
/// Sealed and implemented only for those six types. The bound lets
/// [`DecodeVec::extend_from_le_bytes`] bulk-copy a packed fixed span with one `memcpy`: every bit
/// pattern is a valid value for each of them, so copying raw bytes into the slots soundly
/// initialises them (no invalid-value UB, unlike `bool`/`char`/niche enums).
pub trait FixedLeScalar: Copy + sealed::Sealed {}

macro_rules! impl_fixed_le_scalar {
    ($($t:ty),* $(,)?) => {
        $(
            impl sealed::Sealed for $t {}
            impl FixedLeScalar for $t {}
        )*
    };
}
impl_fixed_le_scalar!(u32, i32, f32, u64, i64, f64);

/// The initial capacity on the first push, then geometric doubling (matching the C++ decoder's
/// start-4-double growth).
const FIRST_CAP: usize = 4;

/// A growable array of decoded `T` backed by `arena`, built during one field loop and finished with
/// [`into_slice`](DecodeVec::into_slice). `T` must be a plain decoded value with no `Drop` (every
/// generated message, scalar, enum, `ProtoStr`, `ProtoBytes` and `PackedSlice` qualifies): a grow
/// relocates the elements with a bitwise copy and never runs their destructors, as the arena requires.
pub struct DecodeVec<'a, T> {
    arena: &'a Arena<'a>,
    ptr: NonNull<T>, // dangling while `cap == 0`
    len: usize,
    cap: usize,
}

impl<'a, T> DecodeVec<'a, T> {
    /// An empty accumulator; allocates nothing until the first [`push`](DecodeVec::push).
    #[inline]
    #[must_use]
    pub fn new(arena: &'a Arena<'a>) -> Self {
        Self {
            arena,
            ptr: NonNull::dangling(),
            len: 0,
            cap: 0,
        }
    }

    /// Append one element, growing the backing array if it is full. `Err(ArenaExhausted)` (never a
    /// panic) if the arena cannot grow.
    #[inline]
    pub fn push(&mut self, value: T) -> Result<(), ArenaExhausted> {
        if self.len == self.cap {
            self.grow()?;
        }
        // SAFETY: after `grow` (or when already non-full) `len < cap`, so `ptr + len` is the next
        // uninitialized slot inside the current array; writing initializes it.
        unsafe { self.ptr.as_ptr().add(self.len).write(value) };
        self.len += 1;
        Ok(())
    }

    /// Decode one element **in place** into the next slot -- no by-value construct-then-copy. Grow if
    /// full, hand the uninitialized tail slot to `f`, and publish it (`len += 1`) only if `f`
    /// succeeds. On `Err`, `len` is unchanged, so the half-written slot is abandoned and never read by
    /// [`into_slice`](Self::into_slice). The Rust equivalent of the C++ decoder's `rp_slot` +
    /// `rp_decode_into(*slot, ...)` for a repeated message element.
    ///
    /// `#[inline(always)]` for the same reason as [`Arena::emplace`](crate::Arena::emplace): the
    /// closure captures the element payload slice by reference, so an out-of-line call pins the 16-byte
    /// `&[u8]` to memory; inlining keeps it in registers and folds the element decode into the caller.
    #[inline(always)]
    pub fn emplace<E, F>(&mut self, f: F) -> Result<(), E>
    where
        E: From<ArenaExhausted>,
        F: for<'id> FnOnce(
            crate::decode_slot::Slot<'id, T>,
        ) -> Result<crate::decode_slot::Init<'id>, E>,
    {
        if self.len == self.cap {
            self.grow()?;
        }
        // SAFETY: after `grow` (or when already non-full) `len < cap`, so `ptr + len` is the in-bounds
        // next slot -- aligned storage for one `T`, valid to write, owned by this `DecodeVec`.
        let slot = unsafe { crate::decode_slot::Slot::new(self.ptr.add(self.len)) };
        // `f` returns `Init<'id>` of this slot's fresh brand, obtainable only by `Slot::write`-ing
        // this slot (unforgeable), so an `Ok` is a compile-time proof the tail slot is initialized --
        // then publish it. On `Err`, `len` is unchanged, so the unwritten slot never reaches
        // `into_slice`. Sound for ANY safe `f`, not a documented contract.
        let _init = f(slot)?;
        self.len += 1;
        Ok(())
    }

    /// Pre-size the backing array so it can hold at least `additional` more elements beyond the
    /// current length, in a SINGLE arena allocation (not the geometric doubling `push` uses).
    /// A no-op when there is already room. Packed decode calls this once from the span's element
    /// count before the fill loop, so the per-element `push`es never trigger a geometric regrow
    /// (mirrors the C++ decoder's `allocate_array` up-front reserve in `emit_packed_fill`).
    #[inline]
    pub fn reserve(&mut self, additional: usize) -> Result<(), ArenaExhausted> {
        let needed = self.len.checked_add(additional).ok_or(ArenaExhausted)?;
        if needed > self.cap {
            self.grow_to(needed)?;
        }
        Ok(())
    }

    /// Trim the backing array to its exact length, returning the unused tail to the arena.
    ///
    /// Packed decode pre-sizes to an upper bound (`reserve`), fills, then calls this to reclaim the
    /// over-estimate (matching the C++ decoder's `Arena::shrink_last` after a packed-varint fill).
    /// The arena can only reclaim while this array is still its most-recent allocation -- true right
    /// after a fill, which allocates nothing; otherwise this just resets the capacity. Afterwards
    /// `cap == len`, so a later `push` regrows (as the C++ decoder resets `rp_cap` to `rp_n`).
    #[inline]
    pub fn shrink_to_fit(&mut self) {
        if self.cap > self.len {
            let size = core::mem::size_of::<T>();
            if size != 0 {
                // SAFETY: `ptr` starts this array, one arena allocation of exactly `cap * size`
                // bytes (`grow_to`). The slots past `len` hold no published element, and with
                // `cap = len` below this `DecodeVec` never touches them again.
                unsafe {
                    self.arena
                        .shrink_last(self.ptr.cast::<u8>(), self.cap * size, self.len * size);
                }
            }
            self.cap = self.len;
        }
    }

    /// Pointer to the start of the reserved-but-uninitialized spare capacity (`ptr + len`). A decode
    /// kernel writes elements directly here after a [`reserve`](Self::reserve), then calls
    /// [`advance_len`](Self::advance_len) to publish them.
    #[inline]
    pub(crate) fn spare_capacity_ptr(&mut self) -> *mut T {
        // SAFETY: `len <= cap`, so `ptr + len` is within the allocation (one-past-end when full).
        // When `cap == 0` the pointer is dangling, but callers only use it after a `reserve` that
        // made room, i.e. `cap > len`.
        unsafe { self.ptr.as_ptr().add(self.len) }
    }

    /// Publish `additional` elements that were written into the spare capacity.
    ///
    /// # Safety
    /// The caller must have initialized exactly `additional` contiguous elements starting at
    /// [`spare_capacity_ptr`](Self::spare_capacity_ptr), with `len + additional <= cap`.
    #[inline]
    pub(crate) unsafe fn advance_len(&mut self, additional: usize) {
        debug_assert!(self.len + additional <= self.cap);
        self.len += additional;
    }

    #[cold]
    fn grow(&mut self) -> Result<(), ArenaExhausted> {
        let new_cap = if self.cap == 0 {
            FIRST_CAP
        } else {
            self.cap.checked_mul(2).ok_or(ArenaExhausted)?
        };
        self.grow_to(new_cap)
    }

    /// Relocate into a fresh arena array of exactly `new_cap` elements (`new_cap > cap`). The old
    /// array is abandoned (the arena never frees); elements move with a bitwise copy.
    fn grow_to(&mut self, new_cap: usize) -> Result<(), ArenaExhausted> {
        debug_assert!(new_cap > self.cap);
        let new = self.arena.alloc_array::<T>(new_cap)?;
        if self.len > 0 {
            // SAFETY: the old array holds `len` initialized `T`s and the new array has room for at
            // least `len`; the two arena allocations are distinct (non-overlapping). A bitwise copy
            // relocates the elements -- sound for a non-`Drop`, non-self-referential `T` (which the
            // arena already requires); the old copies are abandoned, never dropped.
            unsafe { ptr::copy_nonoverlapping(self.ptr.as_ptr(), new.as_ptr(), self.len) };
        }
        self.ptr = new;
        self.cap = new_cap;
        Ok(())
    }

    /// Finish: the pushed elements as a borrowed slice tied to the arena. Empty when nothing was
    /// pushed (no allocation).
    #[inline]
    #[must_use]
    pub fn into_slice(self) -> &'a [T] {
        if self.len == 0 {
            return &[];
        }
        // SAFETY: `ptr` points at `len` contiguous, initialized `T`s in the arena (lifetime `'a`);
        // they are a fresh arena allocation nothing else aliases, and the arena outlives `'a`.
        unsafe { core::slice::from_raw_parts(self.ptr.as_ptr(), self.len) }
    }
}

impl<'a, T: FixedLeScalar> DecodeVec<'a, T> {
    /// Append the packed fixed-width elements whose little-endian wire image is `bytes`, as a single
    /// bulk copy. The generated decoder calls this only for a packed `fixed32`/`fixed64` field on a
    /// little-endian host, after checking `bytes.len()` is a whole multiple of `size_of::<T>()`; any
    /// trailing partial element is ignored (copied as whole elements only, so never out of bounds).
    ///
    /// This reserves the exact element count, copies the span into the array tail with one `memcpy`
    /// (on a little-endian host the span IS the array's native byte image -- protoc fills packed
    /// fixed arrays the same way), and never regrows. The exact reserve means no trim is needed.
    /// `Err(ArenaExhausted)` (never a panic) if the arena cannot grow.
    #[inline]
    pub fn extend_from_le_bytes(&mut self, bytes: &[u8]) -> Result<(), ArenaExhausted> {
        let size = core::mem::size_of::<T>();
        debug_assert!(size != 0 && bytes.len().is_multiple_of(size));
        let count = bytes.len() / size;
        if count == 0 {
            return Ok(());
        }
        self.reserve(count)?;
        // SAFETY: `reserve(count)` guaranteed room for `count` more `T` starting at `ptr + len`, and
        // the arena array is aligned for `T`. `T: FixedLeScalar` is a fixed-width scalar for which
        // every bit pattern is a valid value, so copying `count * size` input bytes into those slots
        // soundly initialises them (the caller guarantees a little-endian host, where the wire image
        // equals the native image). Source (the input span) and destination (a fresh arena array)
        // are distinct allocations, so they never overlap.
        unsafe {
            ptr::copy_nonoverlapping(
                bytes.as_ptr(),
                self.ptr.as_ptr().add(self.len).cast::<u8>(),
                count * size,
            );
        }
        self.len += count;
        Ok(())
    }
}

// The tests build a heap `Arena`, so they need an allocator; gate them on `alloc` (the no-allocator
// tier has no `Arena::new`, matching the arena module's own tests).
#[cfg(all(test, feature = "alloc"))]
mod tests {
    use super::*;

    #[test]
    fn grows_and_preserves_order_across_reallocations() {
        let arena = Arena::new();
        let mut v = DecodeVec::<u32>::new(&arena);
        assert_eq!(v.len, 0);
        // Push well past the initial capacity to force several geometric grows (4 -> 8 -> 16 -> ...).
        for i in 0..100u32 {
            v.push(i * 3).unwrap();
        }
        assert_eq!(v.len, 100);
        let s = v.into_slice();
        assert_eq!(s.len(), 100);
        for (i, &x) in s.iter().enumerate() {
            assert_eq!(x, i as u32 * 3);
        }
    }

    #[test]
    fn empty_is_an_empty_slice_and_allocates_nothing() {
        let arena = Arena::new();
        let v = DecodeVec::<u64>::new(&arena);
        assert_eq!(v.into_slice(), &[] as &[u64]);
        assert_eq!(arena.bytes_used(), 0);
    }

    #[test]
    fn works_for_a_non_copy_relocatable_value() {
        // A move-only (non-Copy) value with no Drop, like a generated message struct: relocation on
        // grow must preserve it.
        #[derive(PartialEq, Debug)]
        struct Pair(u32, u64);
        let arena = Arena::new();
        let mut v = DecodeVec::<Pair>::new(&arena);
        for i in 0..20u32 {
            v.push(Pair(i, u64::from(i) << 40)).unwrap();
        }
        let s = v.into_slice();
        for (i, p) in s.iter().enumerate() {
            assert_eq!(*p, Pair(i as u32, (i as u64) << 40));
        }
    }

    #[test]
    fn reserve_pre_sizes_in_one_allocation_so_pushes_do_not_regrow() {
        let arena = Arena::new();
        let mut v = DecodeVec::<u64>::new(&arena);
        v.reserve(100).unwrap();
        // A single arena allocation of exactly 100 elements -- nothing abandoned yet.
        assert_eq!(arena.bytes_used(), 100 * 8);
        for i in 0..100u64 {
            v.push(i).unwrap();
        }
        // Filling the reserved capacity triggered no geometric regrow (no further allocation).
        assert_eq!(arena.bytes_used(), 100 * 8);
        let s = v.into_slice();
        assert_eq!(s.len(), 100);
        for (i, &x) in s.iter().enumerate() {
            assert_eq!(x, i as u64);
        }
    }

    #[test]
    fn shrink_to_fit_reclaims_the_unused_tail_and_keeps_contents() {
        let arena = Arena::new();
        let mut v = DecodeVec::<u64>::new(&arena);
        // Pre-size to an upper bound, fill fewer (the packed-varint over-estimate case).
        v.reserve(100).unwrap();
        for i in 0..10u64 {
            v.push(i * 7).unwrap();
        }
        assert_eq!(arena.bytes_used(), 100 * 8);
        v.shrink_to_fit();
        // The 90-element tail was returned to the arena; it is still the last allocation.
        assert_eq!(arena.bytes_used(), 10 * 8);
        // A subsequent push regrows (cap was reset to len) and preserves order.
        v.push(999).unwrap();
        let s = v.into_slice();
        assert_eq!(s.len(), 11);
        for (i, &x) in s.iter().take(10).enumerate() {
            assert_eq!(x, i as u64 * 7);
        }
        assert_eq!(s[10], 999);
    }

    #[test]
    fn shrink_to_fit_is_a_noop_when_not_the_last_allocation() {
        let arena = Arena::new();
        let mut v = DecodeVec::<u64>::new(&arena);
        v.reserve(100).unwrap();
        for i in 0..10u64 {
            v.push(i).unwrap();
        }
        // Something else becomes the arena's last allocation, so the tail can no longer be reclaimed.
        let _other = arena.alloc_array::<u64>(4).unwrap();
        let before = arena.bytes_used();
        v.shrink_to_fit();
        // No reclaim (not the last allocation), but the contents stay correct.
        assert_eq!(arena.bytes_used(), before);
        let s = v.into_slice();
        assert_eq!(s.len(), 10);
        for (i, &x) in s.iter().enumerate() {
            assert_eq!(x, i as u64);
        }
    }

    #[test]
    fn push_reports_arena_exhaustion_without_panicking() {
        // A tiny seed-only (no-grow would still be alloc tier here, but cap the heap) arena: cap the
        // capacity so a grow eventually fails cleanly.
        let arena = Arena::new();
        arena.set_capacity_limit(256);
        let mut v = DecodeVec::<u64>::new(&arena);
        let mut pushed = 0usize;
        while v.push(pushed as u64).is_ok() {
            pushed += 1;
            assert!(pushed <= 10_000, "expected the capped arena to exhaust");
        }
        // Whatever fit is intact and in order.
        let got = pushed;
        let s = v.into_slice();
        assert_eq!(s.len(), got);
        for (i, &x) in s.iter().enumerate() {
            assert_eq!(x, i as u64);
        }
    }

    #[test]
    fn extend_from_le_bytes_bulk_copies_fixed_elements_in_one_allocation() {
        let arena = Arena::new();
        let mut v = DecodeVec::<u64>::new(&arena);
        // The little-endian wire image of 50 u64 values.
        let vals: [u64; 50] = core::array::from_fn(|i| (i as u64) << 40 | i as u64);
        let mut bytes = alloc::vec::Vec::new();
        for x in vals {
            bytes.extend_from_slice(&x.to_le_bytes());
        }
        v.extend_from_le_bytes(&bytes).unwrap();
        // Exactly one arena allocation of the exact element count (no over-estimate, no regrow).
        assert_eq!(arena.bytes_used(), 50 * 8);
        let s = v.into_slice();
        assert_eq!(s, &vals[..]);
    }

    #[test]
    fn extend_from_le_bytes_decodes_float_bits_and_appends_after_existing() {
        let arena = Arena::new();
        let mut v = DecodeVec::<f64>::new(&arena);
        // A prior (e.g. unpacked) element already present, then a packed fixed run appended.
        v.push(2.5f64).unwrap();
        let vals = [1.0f64, -0.0, f64::INFINITY, 12345.6789];
        let mut bytes = alloc::vec::Vec::new();
        for x in vals {
            bytes.extend_from_slice(&x.to_le_bytes());
        }
        v.extend_from_le_bytes(&bytes).unwrap();
        let s = v.into_slice();
        assert_eq!(s.len(), 5);
        assert_eq!(s[0], 2.5);
        assert_eq!(s[1], 1.0);
        assert_eq!(s[2], -0.0);
        assert_eq!(s[3], f64::INFINITY);
        assert_eq!(s[4], 12345.6789);
    }

    #[test]
    fn extend_from_le_bytes_empty_is_a_noop() {
        let arena = Arena::new();
        let mut v = DecodeVec::<u32>::new(&arena);
        v.extend_from_le_bytes(&[]).unwrap();
        assert_eq!(v.len, 0);
        assert_eq!(arena.bytes_used(), 0);
        assert_eq!(v.into_slice(), &[] as &[u32]);
    }

    #[test]
    fn emplace_publishes_on_ok_and_abandons_the_slot_on_err() {
        let arena = Arena::new();
        let mut v = DecodeVec::<u64>::new(&arena);
        // Ok: the slot is initialized in place (the returned `&mut` is the write witness) and published.
        v.emplace::<ArenaExhausted, _>(|slot| Ok(slot.write(42)))
            .unwrap();
        assert_eq!(v.len, 1);
        // Err AFTER writing the slot: `len` must NOT advance, so the abandoned (initialized-but-
        // unpublished) slot never reaches `into_slice`. This is the never-crash-on-mid-decode-error
        // invariant at the helper boundary (and is checked under Miri via the gate).
        let r = v.emplace::<ArenaExhausted, _>(|slot| {
            slot.write(999);
            Err(ArenaExhausted)
        });
        assert!(r.is_err());
        assert_eq!(v.len, 1);
        assert_eq!(v.into_slice(), &[42]); // the 999 slot was abandoned, not published
    }
}