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}