Skip to main content

SizeCachePool

Struct SizeCachePool 

Source
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. 1 suffices for sequential reuse (one cache in flight at a time, e.g. a thread_local! pool — see sequential); raise it only for re-entrant or nested encodes that hold several caches at once.
  • max_capacity — the cap, in u32 slots, on each retained buffer’s capacity. One slot holds one nested sub-message’s size; the first 16 are inline-free, so max_capacity = N retains up to N * 4 bytes per buffer and keeps the allocation warm for messages with up to N + 16 nested sub-messages. Set it at or above your steady-state spill size — below it, every encode regrows the buffer and release shrinks 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

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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
Source

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

Trait Implementations§

Source§

impl Debug for SizeCachePool

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.