Skip to main content

buffa/
size_cache.rs

1//! External size cache for linear-time serialization.
2//!
3//! Protobuf's wire format requires knowing the encoded size of a sub-message
4//! before writing it (for the length-delimited prefix). Without caching, each
5//! nesting level recomputes all sizes below it — O(depth²) for chains,
6//! exponential for branchy trees. prost has this problem.
7//!
8//! `SizeCache` records sub-message sizes in a `Vec<u32>` indexed by
9//! pre-order DFS traversal, populated by `compute_size` and consumed in the
10//! same order by `write_to`. Both passes are O(n).
11//!
12//! The cache is external to message structs — generated types hold no
13//! serialization state, so `let Msg { a, b, .. } = m;` is not forced by
14//! hidden plumbing fields. A fresh `SizeCache` is constructed inside the
15//! provided `Message::encode*` / `ViewEncode::encode*` methods; manual
16//! implementers thread it through their `compute_size` / `write_to`.
17//!
18//! # Traversal-order invariant
19//!
20//! `reserve`/`set` calls during `compute_size` must occur in the same
21//! order as `consume_next` calls during `write_to`. Generated code guarantees
22//! this by iterating fields identically in both functions and by guarding
23//! both with identical presence checks (both take `&self`, so the message
24//! is immutable between passes). Manual `Message` implementations must
25//! uphold the same ordering.
26
27use alloc::vec::Vec;
28use core::mem::MaybeUninit;
29
30/// Number of nested-message sizes stored inline (no heap allocation).
31///
32/// `Message::encode*` constructs a fresh `SizeCache` per call, so messages
33/// with ≤ `INLINE_CAP` length-delimited sub-messages encode with zero
34/// allocation for the cache. 16 covers the vast majority of message shapes
35/// (the official protobuf benchmark messages all fit) at 64 bytes of stack.
36const INLINE_CAP: usize = 16;
37
38/// Transient pre-order cache of nested-message sizes for the two-pass
39/// serialization model (`compute_size` populates, `write_to` consumes).
40///
41/// `Message::encode` and friends construct and discard a `SizeCache`
42/// internally — most callers never name this type. It appears in the
43/// `compute_size` / `write_to` signatures so that manual `Message`
44/// implementations can thread it through nested-message recursion.
45///
46/// Storage is a small inline `[u32; 16]` array with a `Vec<u32>` spill for
47/// the (uncommon) case of more than 16 nested length-delimited sub-messages,
48/// so a fresh cache is allocation-free for typical messages.
49///
50/// Reusable across encodes: call [`clear`](Self::clear) between uses to
51/// retain the spill allocation. `SizeCache` is intentionally not `Clone`
52/// — it is transient encode state, not data. Reuse via
53/// [`clear()`](Self::clear).
54///
55/// # Safety invariant
56///
57/// The inline slots are `MaybeUninit` to avoid zeroing the whole array on every
58/// construction (see the field comment). The invariant that keeps the single
59/// `unsafe` read in [`consume_next`](Self::consume_next) sound is:
60///
61/// > every inline slot at an index `< len` has been initialized.
62///
63/// It is established in exactly one place — [`reserve`](Self::reserve) writes
64/// the slot at index `len` *before* incrementing `len` — and `len` only ever
65/// grows via `reserve` (which does that write) or resets to `0` via
66/// [`clear`](Self::clear). `consume_next` only reads a slot after checking
67/// `idx < len`. Because all three methods and the fields are private to this
68/// module, no external code (generated or hand-written) can break the
69/// invariant: the worst a misuse can do is trip the `idx >= len` overrun panic
70/// or read a wrong-but-initialized size — never undefined behavior.
71///
72/// # Panic locations
73///
74/// Generated code calls [`set`](Self::set) once per length-delimited
75/// sub-message field and [`consume_next`](Self::consume_next) once as well, so
76/// a large schema produces hundreds to thousands of call sites for each. Under
77/// `#[track_caller]` every one of them materializes a
78/// [`Location`](core::panic::Location) record. The attribute is therefore
79/// gated on `debug_assertions` and the panic bodies are kept out of line.
80///
81/// The bound checks themselves always run. What changes is the report: without
82/// the attribute a violation points inside `buffa`'s own source rather than at
83/// your `compute_size` / `write_to`. The gate follows the profile **buffa
84/// itself** was compiled with, not yours. To recover caller locations in a
85/// release build, enable them for buffa alone:
86///
87/// ```toml
88/// [profile.release.package.buffa]
89/// debug-assertions = true
90/// ```
91///
92/// This also turns on buffa's other `debug_assert!`s (including a per-slot
93/// size check in [`consume_next`](Self::consume_next)), so treat it as a
94/// diagnostic setting rather than a permanent one.
95pub struct SizeCache {
96    // `MaybeUninit` avoids zeroing the whole array on construction. A fresh
97    // cache is built per encode and handed by `&mut` to an out-of-line
98    // `compute_size`, so the compiler cannot prove the unused tail is never
99    // read and an `[0; INLINE_CAP]` initializer emits `INLINE_CAP / 4` SSE
100    // stores on *every* encode (confirmed by disassembly). With `MaybeUninit`
101    // only the slots actually used are written. See the type's safety invariant.
102    inline: [MaybeUninit<u32>; INLINE_CAP],
103    spill: Vec<u32>,
104    len: u32,
105    cursor: u32,
106}
107
108impl core::fmt::Debug for SizeCache {
109    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
110        // Only the first `len` inline slots are initialized; show those (plus the
111        // spill) so the dump is meaningful without reading uninitialized memory.
112        let inline_init = (self.len as usize).min(INLINE_CAP);
113        // SAFETY: per the type invariant, every inline slot at an index < len is
114        // initialized, so this prefix is sound to view as `&[u32]`.
115        let inline =
116            unsafe { core::slice::from_raw_parts(self.inline.as_ptr().cast::<u32>(), inline_init) };
117        f.debug_struct("SizeCache")
118            .field("len", &self.len)
119            .field("cursor", &self.cursor)
120            .field("inline", &inline)
121            .field("spill", &self.spill)
122            .finish()
123    }
124}
125
126impl Default for SizeCache {
127    #[inline]
128    fn default() -> Self {
129        Self::new()
130    }
131}
132
133impl SizeCache {
134    /// Create an empty cache. No heap allocation.
135    #[inline]
136    #[must_use]
137    pub const fn new() -> Self {
138        Self {
139            inline: [MaybeUninit::uninit(); INLINE_CAP],
140            spill: Vec::new(),
141            len: 0,
142            cursor: 0,
143        }
144    }
145
146    /// Clear the cache for reuse. Retains the spill allocation's capacity.
147    #[inline]
148    pub fn clear(&mut self) {
149        self.spill.clear();
150        self.len = 0;
151        self.cursor = 0;
152    }
153
154    /// Construct a cache that reuses a caller-supplied spill buffer.
155    ///
156    /// The inline storage is always stack-allocated; only the spill `Vec` ever
157    /// heap-allocates, and only for messages with more than 16 nested
158    /// length-delimited sub-messages. Handing in a previously-grown buffer makes
159    /// such an encode allocation-free for the cache. The buffer is cleared (its
160    /// capacity retained). Most callers should reach for a [`SizeCachePool`]
161    /// rather than thread buffers by hand.
162    #[inline]
163    #[must_use]
164    pub fn with_spill_buffer(mut spill: Vec<u32>) -> Self {
165        spill.clear();
166        Self {
167            inline: [MaybeUninit::uninit(); INLINE_CAP],
168            spill,
169            len: 0,
170            cursor: 0,
171        }
172    }
173
174    /// Reclaim the spill buffer for reuse, consuming the cache.
175    ///
176    /// The returned `Vec` retains whatever capacity the cache grew to; feed it
177    /// back into [`with_spill_buffer`](Self::with_spill_buffer) — or let a
178    /// [`SizeCachePool`] manage it — so the next encode reuses the allocation.
179    #[inline]
180    #[must_use]
181    pub fn into_spill_buffer(self) -> Vec<u32> {
182        self.spill
183    }
184
185    /// Reserve a slot for a nested message's size. Call immediately before
186    /// recursing into `child.compute_size(cache)`, then fill the slot with
187    /// [`set`](Self::set) after the recursion returns. This reserves the slot
188    /// in pre-order even though the size is known in post-order.
189    ///
190    /// Used by generated `compute_size` implementations.
191    #[inline]
192    pub fn reserve(&mut self) -> usize {
193        debug_assert!(self.len < u32::MAX, "SizeCache slot count overflow");
194        let idx = self.len as usize;
195        if idx < INLINE_CAP {
196            // Placeholder so a buggy caller that reserves-without-set reads a
197            // deterministic 0, including after `clear()` reuse. This write is
198            // ALSO load-bearing for soundness: it establishes the type
199            // invariant (slots `< len` are initialized) that makes the
200            // `assume_init` in `consume_next` sound. Do not remove it.
201            self.inline[idx] = MaybeUninit::new(0);
202        } else {
203            self.spill.push(0);
204        }
205        self.len += 1;
206        debug_assert_eq!(
207            self.spill.len(),
208            (self.len as usize).saturating_sub(INLINE_CAP),
209            "spill must hold every slot past the inline tier"
210        );
211        idx
212    }
213
214    /// Fill a previously-reserved slot.
215    ///
216    /// Used by generated `compute_size` implementations.
217    ///
218    /// # Panics
219    ///
220    /// Panics if `idx` was not returned by a prior [`reserve`](Self::reserve)
221    /// on this cache (i.e. `idx >= len`). The check always runs; the caller
222    /// location is attached only when buffa is compiled with
223    /// `debug_assertions`. See [Panic locations](Self#panic-locations).
224    #[inline]
225    #[cfg_attr(debug_assertions, track_caller)]
226    pub fn set(&mut self, idx: usize, size: u32) {
227        if idx >= self.len as usize {
228            Self::not_reserved(idx, self.len);
229        }
230        if idx < INLINE_CAP {
231            self.inline[idx] = MaybeUninit::new(size);
232        } else if let Some(slot) = self.spill.get_mut(idx - INLINE_CAP) {
233            *slot = size;
234        } else {
235            Self::spill_desync(idx, self.len, self.spill.len());
236        }
237    }
238
239    /// Consume the next cached size in pre-order.
240    ///
241    /// Used by generated `write_to` implementations for length-delimited
242    /// nested message headers.
243    ///
244    /// # Panics
245    ///
246    /// Panics if the cursor runs past the end of the cache — i.e. if
247    /// `write_to` traversal diverges from `compute_size` traversal. For
248    /// generated code this indicates a codegen bug; for manual `Message`
249    /// implementations it indicates a traversal-order mismatch. As for
250    /// [`set`](Self::set), the check always runs and only the caller location
251    /// is gated on `debug_assertions`. See
252    /// [Panic locations](Self#panic-locations).
253    ///
254    /// In debug builds, also panics if the cached size exceeds the 2 GiB
255    /// protobuf limit ([`MAX_MESSAGE_BYTES`](crate::MAX_MESSAGE_BYTES)):
256    /// every slot is a sub-message length about to become a wire length
257    /// prefix, and no conforming decoder accepts a prefix above the limit.
258    /// This can only fire when `compute_size`/`write_to` are driven directly
259    /// with an over-limit sub-message — the provided `Message::encode*`
260    /// entry points reject over-limit messages before `write_to` runs, so
261    /// (like the two-pass byte ledger) the check is debug-only rather than a
262    /// release-mode branch on every nested-message write.
263    #[inline]
264    #[cfg_attr(debug_assertions, track_caller)]
265    pub fn consume_next(&mut self) -> u32 {
266        let idx = self.cursor as usize;
267        if idx >= self.len as usize {
268            Self::overrun(idx, self.len);
269        }
270        self.cursor += 1;
271        let size = if idx < INLINE_CAP {
272            // SAFETY: `idx < self.len` (checked above) and, per the type
273            // invariant, every inline slot at an index `< len` was initialized
274            // by `reserve` before `len` advanced past it (and possibly
275            // overwritten by `set`), so this slot is initialized.
276            unsafe { self.inline[idx].assume_init() }
277        } else if let Some(&size) = self.spill.get(idx - INLINE_CAP) {
278            size
279        } else {
280            Self::spill_desync(idx, self.len, self.spill.len())
281        };
282        debug_assert!(
283            size <= crate::MAX_MESSAGE_BYTES,
284            "SizeCache slot holds a sub-message length of {size} bytes, \
285             which exceeds the 2 GiB protobuf limit"
286        );
287        size
288    }
289
290    #[cold]
291    #[inline(never)]
292    #[cfg_attr(debug_assertions, track_caller)]
293    fn not_reserved(idx: usize, len: u32) -> ! {
294        panic!("SizeCache::set: slot {idx} not reserved (len {len})")
295    }
296
297    /// Landing pad for the two spill accesses. Unreachable: both are guarded by
298    /// an `idx < len` check, and `reserve` keeps `spill.len()` at `len`
299    /// saturating-minus `INLINE_CAP`. Routed here rather than left to `[]` so
300    /// a broken invariant reports itself by name instead of as a bare
301    /// index-out-of-bounds. Deliberately not `track_caller`: this is a bug in
302    /// buffa, so buffa's own location is the right one to report.
303    #[cold]
304    #[inline(never)]
305    fn spill_desync(idx: usize, len: u32, spill_len: usize) -> ! {
306        panic!(
307            "SizeCache internal invariant broken: slot {idx} is within len \
308             {len} but the spill holds {spill_len} slots"
309        )
310    }
311
312    #[cold]
313    #[inline(never)]
314    #[cfg_attr(debug_assertions, track_caller)]
315    fn overrun(idx: usize, len: u32) -> ! {
316        panic!(
317            "SizeCache cursor overrun: write_to consumed {} slots but \
318             compute_size produced {len} (traversal-order mismatch)",
319            idx + 1,
320        )
321    }
322}
323
324/// A caller-owned free-list of spill buffers that amortizes the [`SizeCache`]
325/// spill allocation across many encodes.
326///
327/// # When you need it
328///
329/// Every `encode` / `encoded_len` builds a fresh [`SizeCache`]. The inline
330/// storage is free (stack, no zeroing), so for messages with at most 16 nested
331/// length-delimited sub-messages there is nothing to pool. Messages that exceed
332/// that — deeply nested, repeated-sub-message shapes — spill to a heap `Vec` on
333/// *every* encode. Routing those through a pool reuses one allocation instead.
334///
335/// ## vs. reusing a single [`SizeCache`]
336///
337/// For plain sequential reuse you don't strictly need a pool: hold one
338/// [`SizeCache`] and call [`encode_with_cache`](crate::Message::encode_with_cache)
339/// with [`clear`](SizeCache::clear) between encodes. The pool adds two things
340/// that bare reuse cannot: it **shrinks an oversized buffer back on return**
341/// (`max_capacity`), so one giant message does not pin peak memory for the
342/// lifetime of the cache, and it supports **multiple caches checked out at once**
343/// (`max_buffers`), so re-entrant or nested encodes each get their own buffer.
344/// If neither matters, a single reused `SizeCache` is simpler.
345///
346/// # Bring your own — buffa holds no global state
347///
348/// You own the pool and decide its scope and lifetime: keep one in a
349/// `thread_local!` for implicit per-thread reuse, or in a request/connection
350/// context for reuse that is freed at that boundary. Only the spill `Vec` is
351/// pooled; each cache's inline storage stays on the stack, so routing a *small*
352/// message through the pool is just a `Vec` pop/push of an empty buffer — no
353/// allocation, no thread-local access, no synchronization. The pool is
354/// `alloc`-only, so it works in `no_std` builds.
355///
356/// # Bounds
357///
358/// Two limits keep memory in check, both set at construction:
359///
360/// - `max_buffers` — how many spill buffers the free-list retains. `1` suffices
361///   for sequential reuse (one cache in flight at a time, e.g. a `thread_local!`
362///   pool — see [`sequential`](Self::sequential)); raise it only for re-entrant
363///   or nested encodes that hold several caches at once.
364/// - `max_capacity` — the cap, in **`u32` slots**, on each retained buffer's
365///   capacity. One slot holds one nested sub-message's size; the first 16 are
366///   inline-free, so `max_capacity = N` retains up to `N * 4` bytes per buffer
367///   and keeps the allocation warm for messages with up to `N + 16` nested
368///   sub-messages. Set it at or above your steady-state spill size — below it,
369///   every encode regrows the buffer and `release` shrinks it back, which is worse
370///   than not pooling. A few hundred is a sensible starting point.
371///
372/// Passing `0` for either bound disables retention (the pool then always
373/// allocates a fresh cache per `acquire`).
374///
375/// # Example: a thread-local pool
376///
377/// ```
378/// use core::cell::RefCell;
379/// use buffa::{Message, SizeCachePool};
380///
381/// thread_local! {
382///     // `const fn new` allows const-initialized thread-locals.
383///     static POOL: RefCell<SizeCachePool> = const { RefCell::new(SizeCachePool::sequential(512)) };
384/// }
385///
386/// fn encode_pooled<M: Message>(msg: &M) -> Vec<u8> {
387///     let mut buf = Vec::new();
388///     POOL.with_borrow_mut(|pool| pool.encode(msg, &mut buf));
389///     buf
390/// }
391/// ```
392#[derive(Debug)]
393pub struct SizeCachePool {
394    free: Vec<Vec<u32>>,
395    max_buffers: usize,
396    max_capacity: usize,
397}
398
399impl SizeCachePool {
400    /// Create an empty pool. No heap allocation until the first encode spills.
401    ///
402    /// `max_buffers` bounds the retained free-list length; `max_capacity` bounds
403    /// each retained buffer's element capacity so a single large message cannot
404    /// pin its peak allocation. For sequential (non-re-entrant) reuse —
405    /// e.g. a `thread_local!` encode buffer — `max_buffers = 1` is enough.
406    #[inline]
407    #[must_use]
408    pub const fn new(max_buffers: usize, max_capacity: usize) -> Self {
409        Self {
410            free: Vec::new(),
411            max_buffers,
412            max_capacity,
413        }
414    }
415
416    /// Create a pool for sequential reuse — one cache checked out at a time.
417    ///
418    /// Equivalent to [`new(1, max_capacity)`](Self::new); the right choice for a
419    /// `thread_local!` or per-request pool where encodes do not nest. Takes only
420    /// the `max_capacity` slot cap (see the [type docs](Self#bounds)), avoiding
421    /// the two-`usize` ordering ambiguity of [`new`](Self::new) for the common
422    /// case.
423    #[inline]
424    #[must_use]
425    pub const fn sequential(max_capacity: usize) -> Self {
426        Self::new(1, max_capacity)
427    }
428
429    /// Check out a cache, reusing a pooled spill buffer if one is available.
430    ///
431    /// Pair with [`release`](Self::release) to return it. The convenience methods
432    /// ([`encode`](Self::encode), [`encode_view`](Self::encode_view),
433    /// [`encoded_len`](Self::encoded_len)) do the acquire/return for you; use
434    /// `acquire`/`release` directly only for manual `compute_size` / `write_to`.
435    #[inline]
436    #[must_use]
437    pub fn acquire(&mut self) -> SizeCache {
438        match self.free.pop() {
439            Some(buf) => SizeCache::with_spill_buffer(buf),
440            None => SizeCache::new(),
441        }
442    }
443
444    /// Return a cache's spill buffer to the pool, honoring both bounds.
445    ///
446    /// A cache that never spilled, or whose buffer shrank to nothing under a
447    /// `max_capacity` of `0`, is dropped rather than retained — the free-list
448    /// never holds a zero-capacity buffer that would yield no reuse.
449    #[inline]
450    pub fn release(&mut self, cache: SizeCache) {
451        if self.free.len() >= self.max_buffers {
452            return;
453        }
454        let mut buf = cache.into_spill_buffer();
455        // Clear first so `shrink_to` is not floored by the live length.
456        buf.clear();
457        if buf.capacity() > self.max_capacity {
458            buf.shrink_to(self.max_capacity);
459        }
460        // After the shrink: skip never-spilled (cap 0) and shrunk-to-0 buffers —
461        // a zero-capacity slot in the free-list yields no reuse on `acquire`.
462        if buf.capacity() == 0 {
463            return;
464        }
465        self.free.push(buf);
466    }
467
468    /// Compute a message's encoded length, reusing a pooled spill buffer.
469    ///
470    /// The pooled equivalent of [`Message::encoded_len`](crate::Message::encoded_len).
471    ///
472    /// # Panics
473    ///
474    /// Panics if the encoded size exceeds the 2 GiB protobuf limit
475    /// ([`MAX_MESSAGE_BYTES`](crate::MAX_MESSAGE_BYTES)), matching the
476    /// non-pooled entry point.
477    #[inline]
478    #[must_use]
479    pub fn encoded_len<M: crate::Message>(&mut self, msg: &M) -> u32 {
480        self.try_encoded_len(msg)
481            .unwrap_or_else(|_| crate::message::encode_size_overflow())
482    }
483
484    /// Encode a message into `buf`, reusing a pooled spill buffer.
485    ///
486    /// The pooled equivalent of [`Message::encode`](crate::Message::encode).
487    ///
488    /// # Panics
489    ///
490    /// Panics if the encoded size exceeds the 2 GiB protobuf limit
491    /// ([`MAX_MESSAGE_BYTES`](crate::MAX_MESSAGE_BYTES)) — inherited from
492    /// [`Message::encode_with_cache`](crate::Message::encode_with_cache).
493    #[inline]
494    pub fn encode<M: crate::Message>(&mut self, msg: &M, buf: &mut impl crate::EncodeSink) {
495        self.try_encode(msg, buf)
496            .unwrap_or_else(|_| crate::message::encode_size_overflow())
497    }
498
499    /// Encode a borrowed message view into `buf`, reusing a pooled spill buffer.
500    ///
501    /// The pooled equivalent of [`ViewEncode::encode`](crate::ViewEncode::encode).
502    ///
503    /// # Panics
504    ///
505    /// Panics if the encoded size exceeds the 2 GiB protobuf limit
506    /// ([`MAX_MESSAGE_BYTES`](crate::MAX_MESSAGE_BYTES)) — inherited from
507    /// [`ViewEncode::encode_with_cache`](crate::ViewEncode::encode_with_cache).
508    #[inline]
509    pub fn encode_view<'a, V: crate::ViewEncode<'a>>(
510        &mut self,
511        view: &V,
512        buf: &mut impl crate::EncodeSink,
513    ) {
514        self.try_encode_view(view, buf)
515            .unwrap_or_else(|_| crate::message::encode_size_overflow())
516    }
517
518    /// Compute a message's encoded length, returning an error instead of
519    /// panicking if it exceeds the 2 GiB protobuf limit
520    /// ([`MAX_MESSAGE_BYTES`](crate::MAX_MESSAGE_BYTES)).
521    ///
522    /// The pooled equivalent of
523    /// [`Message::try_encoded_len`](crate::Message::try_encoded_len).
524    ///
525    /// # Errors
526    ///
527    /// Returns [`EncodeError::MessageTooLarge`](crate::EncodeError::MessageTooLarge)
528    /// if the encoded size exceeds the limit.
529    #[inline]
530    pub fn try_encoded_len<M: crate::Message>(
531        &mut self,
532        msg: &M,
533    ) -> Result<u32, crate::EncodeError> {
534        let mut cache = self.acquire();
535        let len = msg.compute_size(&mut cache);
536        self.release(cache);
537        crate::message::checked_encode_size(len)
538    }
539
540    /// Encode a message into `buf`, returning an error instead of panicking
541    /// if the encoded size exceeds the 2 GiB protobuf limit
542    /// ([`MAX_MESSAGE_BYTES`](crate::MAX_MESSAGE_BYTES)). Reuses a pooled
543    /// spill buffer.
544    ///
545    /// The pooled equivalent of
546    /// [`Message::try_encode`](crate::Message::try_encode). On `Err`,
547    /// nothing is written to `buf` and the pooled buffer is returned to the
548    /// pool.
549    ///
550    /// # Errors
551    ///
552    /// Returns [`EncodeError::MessageTooLarge`](crate::EncodeError::MessageTooLarge)
553    /// if the encoded size exceeds the limit.
554    #[inline]
555    pub fn try_encode<M: crate::Message>(
556        &mut self,
557        msg: &M,
558        buf: &mut impl crate::EncodeSink,
559    ) -> Result<(), crate::EncodeError> {
560        let mut cache = self.acquire();
561        let result = msg.try_encode_with_cache(&mut cache, buf);
562        self.release(cache);
563        result
564    }
565
566    /// Encode a borrowed message view into `buf`, returning an error
567    /// instead of panicking if the encoded size exceeds the 2 GiB protobuf
568    /// limit ([`MAX_MESSAGE_BYTES`](crate::MAX_MESSAGE_BYTES)). Reuses a
569    /// pooled spill buffer.
570    ///
571    /// The pooled equivalent of
572    /// [`ViewEncode::try_encode`](crate::ViewEncode::try_encode). On `Err`,
573    /// nothing is written to `buf` and the pooled buffer is returned to the
574    /// pool.
575    ///
576    /// # Errors
577    ///
578    /// Returns [`EncodeError::MessageTooLarge`](crate::EncodeError::MessageTooLarge)
579    /// if the encoded size exceeds the limit.
580    #[inline]
581    pub fn try_encode_view<'a, V: crate::ViewEncode<'a>>(
582        &mut self,
583        view: &V,
584        buf: &mut impl crate::EncodeSink,
585    ) -> Result<(), crate::EncodeError> {
586        let mut cache = self.acquire();
587        let result = view.try_encode_with_cache(&mut cache, buf);
588        self.release(cache);
589        result
590    }
591
592    /// Encode a message into `buf` only if its encoded size fits within
593    /// `max_bytes`, reusing a pooled spill buffer.
594    ///
595    /// The pooled equivalent of
596    /// [`Message::try_encode_bounded`](crate::Message::try_encode_bounded).
597    /// Uses a single size pass: `compute_size` populates the cache, the
598    /// budget check fires before `write_to`, so on `Err` nothing is written
599    /// to `buf` and the pooled buffer is returned to the pool.
600    ///
601    /// Returns the encoded body length on success (excludes any length prefix
602    /// you add for framing). `max_bytes` is `u32` to match the encode-size
603    /// domain; callers with a `usize` budget can cast with
604    /// `u32::try_from(budget).unwrap_or(u32::MAX)`.
605    ///
606    /// # Errors
607    ///
608    /// - [`EncodeError::MessageTooLarge`](crate::EncodeError::MessageTooLarge)
609    ///   if the encoded size exceeds the 2 GiB protobuf limit
610    ///   ([`MAX_MESSAGE_BYTES`](crate::MAX_MESSAGE_BYTES)).
611    ///   `MessageTooLarge` takes precedence if both limits are exceeded.
612    /// - [`EncodeError::ExceedsBudget`](crate::EncodeError::ExceedsBudget)
613    ///   if the encoded size is within the protobuf limit but exceeds
614    ///   `max_bytes`.
615    #[inline]
616    pub fn try_encode_bounded<M: crate::Message>(
617        &mut self,
618        msg: &M,
619        max_bytes: u32,
620        buf: &mut impl crate::EncodeSink,
621    ) -> Result<u32, crate::EncodeError> {
622        let mut cache = self.acquire();
623        let result = msg.try_encode_bounded_with_cache(max_bytes, &mut cache, buf);
624        self.release(cache);
625        result
626    }
627
628    /// Encode a borrowed message view into `buf` only if its encoded size
629    /// fits within `max_bytes`, reusing a pooled spill buffer.
630    ///
631    /// The pooled equivalent of
632    /// [`ViewEncode::try_encode_bounded`](crate::ViewEncode::try_encode_bounded).
633    /// Uses a single size pass: `compute_size` populates the cache, the
634    /// budget check fires before `write_to`, so on `Err` nothing is written
635    /// to `buf` and the pooled buffer is returned to the pool.
636    ///
637    /// Returns the encoded body length on success (excludes any length prefix
638    /// you add for framing). `max_bytes` is `u32` to match the encode-size
639    /// domain; callers with a `usize` budget can cast with
640    /// `u32::try_from(budget).unwrap_or(u32::MAX)`.
641    ///
642    /// # Errors
643    ///
644    /// - [`EncodeError::MessageTooLarge`](crate::EncodeError::MessageTooLarge)
645    ///   if the encoded size exceeds the 2 GiB protobuf limit
646    ///   ([`MAX_MESSAGE_BYTES`](crate::MAX_MESSAGE_BYTES)).
647    ///   `MessageTooLarge` takes precedence if both limits are exceeded.
648    /// - [`EncodeError::ExceedsBudget`](crate::EncodeError::ExceedsBudget)
649    ///   if the encoded size is within the protobuf limit but exceeds
650    ///   `max_bytes`.
651    #[inline]
652    pub fn try_encode_view_bounded<'a, V: crate::ViewEncode<'a>>(
653        &mut self,
654        view: &V,
655        max_bytes: u32,
656        buf: &mut impl crate::EncodeSink,
657    ) -> Result<u32, crate::EncodeError> {
658        let mut cache = self.acquire();
659        let result = view.try_encode_bounded_with_cache(max_bytes, &mut cache, buf);
660        self.release(cache);
661        result
662    }
663}
664
665#[cfg(test)]
666mod tests {
667    use super::*;
668
669    // Several tests below bake literal slot numbers into expected panic
670    // messages; they assume the inline tier is 16 slots.
671    const _: () = assert!(INLINE_CAP == 16);
672
673    #[test]
674    fn empty_cache_is_default() {
675        let c = SizeCache::new();
676        assert_eq!(c.len, 0);
677        assert_eq!(c.cursor, 0);
678        assert!(c.spill.is_empty());
679    }
680
681    #[test]
682    fn spill_past_inline_cap_preserves_order() {
683        const N: usize = INLINE_CAP * 2 + 5;
684        let mut c = SizeCache::new();
685        let slots: alloc::vec::Vec<usize> = (0..N).map(|_| c.reserve()).collect();
686        // Fill in reverse to prove set() addresses by slot index, not push order.
687        for (i, &s) in slots.iter().enumerate().rev() {
688            c.set(s, i as u32 * 7);
689        }
690        assert_eq!(c.spill.len(), N - INLINE_CAP);
691        for i in 0..N {
692            assert_eq!(c.consume_next(), i as u32 * 7);
693        }
694    }
695
696    #[test]
697    fn boundary_at_inline_cap() {
698        let mut c = SizeCache::new();
699        for i in 0..INLINE_CAP {
700            let s = c.reserve();
701            c.set(s, i as u32);
702        }
703        assert!(c.spill.is_empty(), "no spill at exactly INLINE_CAP");
704        let s = c.reserve();
705        c.set(s, 999);
706        assert_eq!(c.spill.len(), 1);
707        for i in 0..INLINE_CAP {
708            assert_eq!(c.consume_next(), i as u32);
709        }
710        assert_eq!(c.consume_next(), 999);
711    }
712
713    #[test]
714    fn reserve_set_next_roundtrip() {
715        let mut c = SizeCache::new();
716        let s0 = c.reserve();
717        let s1 = c.reserve();
718        c.set(s0, 10);
719        c.set(s1, 20);
720        assert_eq!(c.consume_next(), 10);
721        assert_eq!(c.consume_next(), 20);
722    }
723
724    #[test]
725    fn preorder_reservation_with_nested_recursion() {
726        // Simulates: root has children [A, B]; A has child X.
727        // compute_size pre-order entry: A, X, B
728        // write_to consumes in the same order.
729        let mut c = SizeCache::new();
730
731        // compute root:
732        //   reserve slot for A
733        let slot_a = c.reserve();
734        //     compute A:
735        //       reserve slot for X
736        let slot_x = c.reserve();
737        //         compute X: leaf, no nested messages, returns 5
738        c.set(slot_x, 5);
739        //       A returns 7 (includes X's 5 plus framing)
740        c.set(slot_a, 7);
741        //   reserve slot for B
742        let slot_b = c.reserve();
743        //     compute B: leaf, returns 3
744        c.set(slot_b, 3);
745
746        // write_to root consumes A, X, B in pre-order:
747        assert_eq!(c.consume_next(), 7); // A's length prefix
748        assert_eq!(c.consume_next(), 5); // X's length prefix (inside A.write_to)
749        assert_eq!(c.consume_next(), 3); // B's length prefix
750    }
751
752    #[test]
753    fn clear_resets_and_retains_capacity() {
754        let mut c = SizeCache::new();
755        for _ in 0..(INLINE_CAP + 4) {
756            c.reserve();
757        }
758        let cap = c.spill.capacity();
759        assert!(cap >= 4);
760        c.clear();
761        assert_eq!(c.len, 0);
762        assert_eq!(c.cursor, 0);
763        assert!(c.spill.capacity() >= cap);
764        // Reusable after clear:
765        let s = c.reserve();
766        c.set(s, 99);
767        assert_eq!(c.consume_next(), 99);
768    }
769
770    #[test]
771    fn reserve_without_set_yields_zero() {
772        let mut c = SizeCache::new();
773        let _ = c.reserve();
774        assert_eq!(c.consume_next(), 0);
775    }
776
777    #[test]
778    fn clear_then_reserve_without_set_yields_zero() {
779        let mut c = SizeCache::new();
780        for i in 0..(INLINE_CAP + 3) {
781            let s = c.reserve();
782            c.set(s, (i + 100) as u32);
783        }
784        c.clear();
785        // After clear, a fresh reserve() must overwrite stale inline data.
786        let _ = c.reserve();
787        assert_eq!(c.consume_next(), 0);
788    }
789
790    #[test]
791    #[should_panic(expected = "SizeCache cursor overrun")]
792    fn next_past_end_panics() {
793        let mut c = SizeCache::new();
794        c.consume_next();
795    }
796
797    /// Exercises the inline/spill boundary with out-of-order `set` and a
798    /// `clear`-and-reuse cycle. Run under `cargo +nightly miri test` this is the
799    /// mechanical check that `consume_next`'s `assume_init` never reads
800    /// uninitialized memory: every `reserve`d slot below `len` must be init.
801    #[test]
802    fn miri_soundness_interleaved_reserve_set_consume() {
803        let mut c = SizeCache::new();
804        // Two full inline tiers' worth, crossing the spill boundary.
805        let n = INLINE_CAP * 2 + 3;
806        let slots: Vec<usize> = (0..n).map(|_| c.reserve()).collect();
807        // Fill out of order (reverse) to decouple set order from reserve order.
808        for (i, &s) in slots.iter().enumerate().rev() {
809            c.set(s, (i as u32).wrapping_mul(3).wrapping_add(1));
810        }
811        for i in 0..n {
812            assert_eq!(c.consume_next(), (i as u32).wrapping_mul(3).wrapping_add(1));
813        }
814        // Reuse: a shorter run must not read stale/uninit tail slots.
815        c.clear();
816        let a = c.reserve();
817        let b = c.reserve();
818        c.set(b, 20);
819        // `a` reserved-but-not-set -> deterministic 0 (placeholder write).
820        assert_eq!(c.consume_next(), 0);
821        assert_eq!(c.consume_next(), 20);
822        let _ = a;
823    }
824
825    // ── SizeCachePool ────────────────────────────────────────────────────
826
827    /// Drive a cache from the pool through enough reserves to force a spill,
828    /// fill the slots, then return it.
829    fn spill_and_return(pool: &mut SizeCachePool, slots: usize) {
830        let mut c = pool.acquire();
831        for i in 0..slots {
832            let s = c.reserve();
833            c.set(s, i as u32);
834        }
835        pool.release(c);
836    }
837
838    #[test]
839    fn with_spill_buffer_clears_and_retains_capacity() {
840        let mut donor = Vec::with_capacity(40);
841        donor.extend_from_slice(&[7, 7, 7]);
842        let cap = donor.capacity();
843        let c = SizeCache::with_spill_buffer(donor);
844        assert_eq!(c.len, 0);
845        assert!(c.spill.is_empty());
846        assert!(c.spill.capacity() >= cap, "retains donor capacity");
847    }
848
849    #[test]
850    fn into_spill_buffer_roundtrips_through_with_spill_buffer() {
851        let mut c = SizeCache::new();
852        for _ in 0..(INLINE_CAP + 5) {
853            c.reserve();
854        }
855        let buf = c.into_spill_buffer();
856        let grown = buf.capacity();
857        assert!(grown >= 5);
858        let c2 = SizeCache::with_spill_buffer(buf);
859        assert!(c2.spill.capacity() >= grown, "allocation reused");
860        assert_eq!(c2.len, 0);
861    }
862
863    #[test]
864    fn pool_reuses_spill_allocation() {
865        let mut pool = SizeCachePool::new(4, 1024);
866        spill_and_return(&mut pool, INLINE_CAP + 5);
867        assert_eq!(pool.free.len(), 1, "spilled buffer retained");
868        let grown = pool.free[0].capacity();
869        // Next acquire hands back the grown buffer.
870        let c = pool.acquire();
871        assert!(c.spill.capacity() >= grown, "spill capacity reused");
872        assert_eq!(c.len, 0);
873    }
874
875    #[test]
876    fn pool_does_not_retain_non_spilling_caches() {
877        let mut pool = SizeCachePool::new(4, 1024);
878        let mut c = pool.acquire();
879        let s = c.reserve(); // stays inline, no heap buffer
880        c.set(s, 1);
881        pool.release(c);
882        assert!(pool.free.is_empty(), "empty (cap 0) buffers are not pooled");
883    }
884
885    #[test]
886    fn pool_respects_max_buffers() {
887        let mut pool = SizeCachePool::new(1, 1024);
888        for _ in 0..3 {
889            spill_and_return(&mut pool, INLINE_CAP + 2);
890        }
891        assert!(pool.free.len() <= 1, "free-list bounded by max_buffers");
892    }
893
894    #[test]
895    fn pool_shrinks_oversized_buffer_on_return() {
896        let mut pool = SizeCachePool::new(4, 8);
897        spill_and_return(&mut pool, INLINE_CAP + 100);
898        assert!(
899            pool.free[0].capacity() <= 8,
900            "oversized buffer shrunk to cap"
901        );
902    }
903
904    #[test]
905    fn pool_acquire_release_default_is_empty() {
906        let mut pool = SizeCachePool::new(2, 64);
907        let c = pool.acquire(); // empty pool -> fresh cache
908        assert_eq!(c.len, 0);
909        pool.release(c); // never spilled -> dropped
910        assert!(pool.free.is_empty());
911    }
912
913    #[test]
914    fn pool_sequential_caps_buffers_at_one() {
915        let mut pool = SizeCachePool::sequential(1024);
916        assert_eq!(pool.max_buffers, 1);
917        for _ in 0..3 {
918            spill_and_return(&mut pool, INLINE_CAP + 2);
919        }
920        assert_eq!(pool.free.len(), 1, "sequential retains exactly one buffer");
921    }
922
923    #[test]
924    fn pool_max_capacity_zero_disables_retention() {
925        let mut pool = SizeCachePool::new(4, 0);
926        // Even a spilled buffer shrinks to 0 and must not be parked empty.
927        spill_and_return(&mut pool, INLINE_CAP + 50);
928        assert!(
929            pool.free.is_empty(),
930            "max_capacity 0 retains no (zero-capacity) buffers"
931        );
932        // And the pool still yields a usable cache.
933        let mut c = pool.acquire();
934        let s = c.reserve();
935        c.set(s, 9);
936        assert_eq!(c.consume_next(), 9);
937    }
938
939    #[test]
940    fn consume_next_allows_exactly_max_message_bytes() {
941        let mut c = SizeCache::new();
942        let s = c.reserve();
943        c.set(s, crate::MAX_MESSAGE_BYTES);
944        assert_eq!(c.consume_next(), crate::MAX_MESSAGE_BYTES);
945    }
946
947    #[test]
948    #[should_panic(expected = "slot 0 not reserved (len 0)")]
949    fn set_unreserved_slot_panics() {
950        let mut c = SizeCache::new();
951        c.set(0, 7);
952    }
953
954    /// A spill-tier index past the end reports as unreserved, not as the
955    /// internal `spill_desync`: the leading `idx >= len` check dominates the
956    /// `get_mut`, which is what makes that arm unreachable. The two carry
957    /// distinct messages, so this pins which one fired.
958    #[test]
959    #[should_panic(expected = "slot 20 not reserved (len 17)")]
960    fn set_past_spill_end_reports_unreserved() {
961        let mut c = SizeCache::new();
962        for _ in 0..=INLINE_CAP {
963            let _ = c.reserve();
964        }
965        c.set(INLINE_CAP + 4, 7);
966    }
967
968    /// `spill_desync` is unreachable through the public API, so break the
969    /// invariant by hand to pin its message (and its argument order — `idx`
970    /// and `spill_len` are both `usize`).
971    #[test]
972    #[should_panic(expected = "slot 16 is within len 17 but the spill holds 0 slots")]
973    fn set_reports_spill_desync_when_invariant_broken() {
974        let mut c = SizeCache::new();
975        for _ in 0..=INLINE_CAP {
976            let _ = c.reserve();
977        }
978        c.spill.clear();
979        c.set(INLINE_CAP, 1);
980    }
981
982    #[test]
983    #[should_panic(expected = "slot 16 is within len 17 but the spill holds 0 slots")]
984    fn consume_next_reports_spill_desync_when_invariant_broken() {
985        let mut c = SizeCache::new();
986        for _ in 0..=INLINE_CAP {
987            let idx = c.reserve();
988            c.set(idx, 1);
989        }
990        c.spill.clear();
991        for _ in 0..=INLINE_CAP {
992            let _ = c.consume_next();
993        }
994    }
995
996    /// `clear` must empty the spill, not just reset `len`. If it stopped doing
997    /// so the spill would outlive its slots and `consume_next` would hand back
998    /// stale sizes from shifted indices, corrupting the wire output silently
999    /// rather than panicking.
1000    #[test]
1001    fn clear_empties_spill_and_reuse_reads_back_new_values() {
1002        let mut c = SizeCache::new();
1003        for _ in 0..INLINE_CAP + 2 {
1004            let s = c.reserve();
1005            c.set(s, 111);
1006        }
1007        c.clear();
1008        assert!(c.spill.is_empty());
1009        for _ in 0..INLINE_CAP + 2 {
1010            let s = c.reserve();
1011            c.set(s, 222);
1012        }
1013        assert_eq!(c.spill.len(), 2);
1014        for _ in 0..INLINE_CAP + 2 {
1015            assert_eq!(c.consume_next(), 222);
1016        }
1017    }
1018
1019    /// The spill arm's `get_mut` is unreachable-`None` because `reserve` keeps
1020    /// `spill.len()` at `len` saturating-minus `INLINE_CAP`. Pin that at the
1021    /// boundary and one slot past it, since `set` now relies on it.
1022    #[test]
1023    fn spill_len_tracks_len_past_inline_cap() {
1024        let mut c = SizeCache::new();
1025        for i in 0..INLINE_CAP + 2 {
1026            let idx = c.reserve();
1027            assert_eq!(idx, i);
1028            assert_eq!(c.len as usize, i + 1);
1029            assert_eq!(c.spill.len(), (i + 1).saturating_sub(INLINE_CAP));
1030        }
1031        // The last reserved slot is in the spill tier and `set` reaches it.
1032        c.set(INLINE_CAP + 1, 99);
1033        for _ in 0..=INLINE_CAP {
1034            let _ = c.consume_next();
1035        }
1036        assert_eq!(c.consume_next(), 99);
1037    }
1038
1039    #[cfg(debug_assertions)]
1040    #[test]
1041    #[should_panic(expected = "exceeds the 2 GiB protobuf limit")]
1042    fn consume_next_rejects_oversized_slot() {
1043        // A slot above the limit would become an invalid wire length
1044        // prefix. The entry points reject such messages before write_to
1045        // runs; this debug-only backstop covers direct compute_size/write_to
1046        // drivers.
1047        let mut c = SizeCache::new();
1048        let s = c.reserve();
1049        c.set(s, crate::MAX_MESSAGE_BYTES + 1);
1050        c.consume_next();
1051    }
1052}