pub struct SizeCachePool { /* private fields */ }Expand description
A caller-owned free-list of spill buffers that amortizes the SizeCache
spill allocation across many encodes.
§When you need it
Every encode / encoded_len builds a fresh SizeCache. The inline
storage is free (stack, no zeroing), so for messages with at most 16 nested
length-delimited sub-messages there is nothing to pool. Messages that exceed
that — deeply nested, repeated-sub-message shapes — spill to a heap Vec on
every encode. Routing those through a pool reuses one allocation instead.
§vs. reusing a single SizeCache
For plain sequential reuse you don’t strictly need a pool: hold one
SizeCache and call encode_with_cache
with clear between encodes. The pool adds two things
that bare reuse cannot: it shrinks an oversized buffer back on return
(max_capacity), so one giant message does not pin peak memory for the
lifetime of the cache, and it supports multiple caches checked out at once
(max_buffers), so re-entrant or nested encodes each get their own buffer.
If neither matters, a single reused SizeCache is simpler.
§Bring your own — buffa holds no global state
You own the pool and decide its scope and lifetime: keep one in a
thread_local! for implicit per-thread reuse, or in a request/connection
context for reuse that is freed at that boundary. Only the spill Vec is
pooled; each cache’s inline storage stays on the stack, so routing a small
message through the pool is just a Vec pop/push of an empty buffer — no
allocation, no thread-local access, no synchronization. The pool is
alloc-only, so it works in no_std builds.
§Bounds
Two limits keep memory in check, both set at construction:
max_buffers— how many spill buffers the free-list retains.1suffices for sequential reuse (one cache in flight at a time, e.g. athread_local!pool — seesequential); raise it only for re-entrant or nested encodes that hold several caches at once.max_capacity— the cap, inu32slots, on each retained buffer’s capacity. One slot holds one nested sub-message’s size; the first 16 are inline-free, somax_capacity = Nretains up toN * 4bytes per buffer and keeps the allocation warm for messages with up toN + 16nested sub-messages. Set it at or above your steady-state spill size — below it, every encode regrows the buffer andreleaseshrinks it back, which is worse than not pooling. A few hundred is a sensible starting point.
Passing 0 for either bound disables retention (the pool then always
allocates a fresh cache per acquire).
§Example: a thread-local pool
use core::cell::RefCell;
use buffa::{Message, SizeCachePool};
thread_local! {
// `const fn new` allows const-initialized thread-locals.
static POOL: RefCell<SizeCachePool> = const { RefCell::new(SizeCachePool::sequential(512)) };
}
fn encode_pooled<M: Message>(msg: &M) -> Vec<u8> {
let mut buf = Vec::new();
POOL.with_borrow_mut(|pool| pool.encode(msg, &mut buf));
buf
}Implementations§
Source§impl SizeCachePool
impl SizeCachePool
Sourcepub const fn new(max_buffers: usize, max_capacity: usize) -> Self
pub const fn new(max_buffers: usize, max_capacity: usize) -> Self
Create an empty pool. No heap allocation until the first encode spills.
max_buffers bounds the retained free-list length; max_capacity bounds
each retained buffer’s element capacity so a single large message cannot
pin its peak allocation. For sequential (non-re-entrant) reuse —
e.g. a thread_local! encode buffer — max_buffers = 1 is enough.
Sourcepub const fn sequential(max_capacity: usize) -> Self
pub const fn sequential(max_capacity: usize) -> Self
Create a pool for sequential reuse — one cache checked out at a time.
Equivalent to new(1, max_capacity); the right choice for a
thread_local! or per-request pool where encodes do not nest. Takes only
the max_capacity slot cap (see the type docs), avoiding
the two-usize ordering ambiguity of new for the common
case.
Sourcepub fn acquire(&mut self) -> SizeCache
pub fn acquire(&mut self) -> SizeCache
Check out a cache, reusing a pooled spill buffer if one is available.
Pair with release to return it. The convenience methods
(encode, encode_view,
encoded_len) do the acquire/return for you; use
acquire/release directly only for manual compute_size / write_to.
Sourcepub fn release(&mut self, cache: SizeCache)
pub fn release(&mut self, cache: SizeCache)
Return a cache’s spill buffer to the pool, honoring both bounds.
A cache that never spilled, or whose buffer shrank to nothing under a
max_capacity of 0, is dropped rather than retained — the free-list
never holds a zero-capacity buffer that would yield no reuse.
Sourcepub fn encoded_len<M: Message>(&mut self, msg: &M) -> u32
pub fn encoded_len<M: Message>(&mut self, msg: &M) -> u32
Compute a message’s encoded length, reusing a pooled spill buffer.
The pooled equivalent of Message::encoded_len.
§Panics
Panics if the encoded size exceeds the 2 GiB protobuf limit
(MAX_MESSAGE_BYTES), matching the
non-pooled entry point.
Sourcepub fn encode<M: Message>(&mut self, msg: &M, buf: &mut impl EncodeSink)
pub fn encode<M: Message>(&mut self, msg: &M, buf: &mut impl EncodeSink)
Encode a message into buf, reusing a pooled spill buffer.
The pooled equivalent of Message::encode.
§Panics
Panics if the encoded size exceeds the 2 GiB protobuf limit
(MAX_MESSAGE_BYTES) — inherited from
Message::encode_with_cache.
Sourcepub fn encode_view<'a, V: ViewEncode<'a>>(
&mut self,
view: &V,
buf: &mut impl EncodeSink,
)
pub fn encode_view<'a, V: ViewEncode<'a>>( &mut self, view: &V, buf: &mut impl EncodeSink, )
Encode a borrowed message view into buf, reusing a pooled spill buffer.
The pooled equivalent of ViewEncode::encode.
§Panics
Panics if the encoded size exceeds the 2 GiB protobuf limit
(MAX_MESSAGE_BYTES) — inherited from
ViewEncode::encode_with_cache.
Sourcepub fn try_encoded_len<M: Message>(
&mut self,
msg: &M,
) -> Result<u32, EncodeError>
pub fn try_encoded_len<M: Message>( &mut self, msg: &M, ) -> Result<u32, EncodeError>
Compute a message’s encoded length, returning an error instead of
panicking if it exceeds the 2 GiB protobuf limit
(MAX_MESSAGE_BYTES).
The pooled equivalent of
Message::try_encoded_len.
§Errors
Returns EncodeError::MessageTooLarge
if the encoded size exceeds the limit.
Sourcepub fn try_encode<M: Message>(
&mut self,
msg: &M,
buf: &mut impl EncodeSink,
) -> Result<(), EncodeError>
pub fn try_encode<M: Message>( &mut self, msg: &M, buf: &mut impl EncodeSink, ) -> Result<(), EncodeError>
Encode a message into buf, returning an error instead of panicking
if the encoded size exceeds the 2 GiB protobuf limit
(MAX_MESSAGE_BYTES). Reuses a pooled
spill buffer.
The pooled equivalent of
Message::try_encode. On Err,
nothing is written to buf and the pooled buffer is returned to the
pool.
§Errors
Returns EncodeError::MessageTooLarge
if the encoded size exceeds the limit.
Sourcepub fn try_encode_view<'a, V: ViewEncode<'a>>(
&mut self,
view: &V,
buf: &mut impl EncodeSink,
) -> Result<(), EncodeError>
pub fn try_encode_view<'a, V: ViewEncode<'a>>( &mut self, view: &V, buf: &mut impl EncodeSink, ) -> Result<(), EncodeError>
Encode a borrowed message view into buf, returning an error
instead of panicking if the encoded size exceeds the 2 GiB protobuf
limit (MAX_MESSAGE_BYTES). Reuses a
pooled spill buffer.
The pooled equivalent of
ViewEncode::try_encode. On Err,
nothing is written to buf and the pooled buffer is returned to the
pool.
§Errors
Returns EncodeError::MessageTooLarge
if the encoded size exceeds the limit.
Sourcepub fn try_encode_bounded<M: Message>(
&mut self,
msg: &M,
max_bytes: u32,
buf: &mut impl EncodeSink,
) -> Result<u32, EncodeError>
pub fn try_encode_bounded<M: Message>( &mut self, msg: &M, max_bytes: u32, buf: &mut impl EncodeSink, ) -> Result<u32, EncodeError>
Encode a message into buf only if its encoded size fits within
max_bytes, reusing a pooled spill buffer.
The pooled equivalent of
Message::try_encode_bounded.
Uses a single size pass: compute_size populates the cache, the
budget check fires before write_to, so on Err nothing is written
to buf and the pooled buffer is returned to the pool.
Returns the encoded body length on success (excludes any length prefix
you add for framing). max_bytes is u32 to match the encode-size
domain; callers with a usize budget can cast with
u32::try_from(budget).unwrap_or(u32::MAX).
§Errors
EncodeError::MessageTooLargeif the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).MessageTooLargetakes precedence if both limits are exceeded.EncodeError::ExceedsBudgetif the encoded size is within the protobuf limit but exceedsmax_bytes.
Sourcepub fn try_encode_view_bounded<'a, V: ViewEncode<'a>>(
&mut self,
view: &V,
max_bytes: u32,
buf: &mut impl EncodeSink,
) -> Result<u32, EncodeError>
pub fn try_encode_view_bounded<'a, V: ViewEncode<'a>>( &mut self, view: &V, max_bytes: u32, buf: &mut impl EncodeSink, ) -> Result<u32, EncodeError>
Encode a borrowed message view into buf only if its encoded size
fits within max_bytes, reusing a pooled spill buffer.
The pooled equivalent of
ViewEncode::try_encode_bounded.
Uses a single size pass: compute_size populates the cache, the
budget check fires before write_to, so on Err nothing is written
to buf and the pooled buffer is returned to the pool.
Returns the encoded body length on success (excludes any length prefix
you add for framing). max_bytes is u32 to match the encode-size
domain; callers with a usize budget can cast with
u32::try_from(budget).unwrap_or(u32::MAX).
§Errors
EncodeError::MessageTooLargeif the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).MessageTooLargetakes precedence if both limits are exceeded.EncodeError::ExceedsBudgetif the encoded size is within the protobuf limit but exceedsmax_bytes.