Skip to main content

ProtoBox

Trait ProtoBox 

Source
pub trait ProtoBox<T>: Deref<Target = T> + DerefMut {
    // Required methods
    fn new(value: T) -> Self;
    fn into_inner(self) -> T;
}
Expand description

The owned smart pointer backing a singular message field inside MessageField.

The codegen default is Inline<T> — the message is stored directly in the parent struct (no heap), with recursive fields kept on Box<T> automatically. buffa_build’s box_type_in selects Box<T> (or a custom pointer) for fields where reserving size_of::<T>() in the parent is wasteful. The box_type_custom knob substitutes any pointer that implements ProtoBox<T> — for example a smallbox-style pointer that stores small messages inline but spills large ones to the heap. The wire format is unchanged; only the in-memory ownership of the boxed message changes, and view types are unaffected.

There is intentionally no blanket impl — the built-in Box<T> and Inline<T> impls below are the only ones buffa provides. Because ProtoBox is buffa-owned, a foreign pointer cannot implement it directly (orphan rule); wrap it in a crate-local newtype, like the ProtoString newtype pattern.

§Why DerefMut (and why Rc / Arc are excluded)

The decoder merges a message field in place — it calls get_or_insert_default to obtain a &mut T and decodes into it. That requires DerefMut, which Rc<T> and Arc<T> cannot provide while shared. So this knob selects an allocation strategy (inline vs heap) for an exclusively-owned message, never a shared or copy-on-write pointer. A custom pointer that is not exclusively owned will fail to implement ProtoBox at its definition site, not silently misbehave.

§Thread-safety

ProtoBox deliberately does not require Send/Sync (unlike ProtoString/ProtoBytes/ProtoList). MessageField<T> is the universal message-field wrapper and has generic helpers; bounding the pointer Send + Sync would tighten T: Send + Sync onto all of them. It is also unnecessary: a generated message implements Message, whose Send + Sync supertraits already require every field — and thus the pointer — to be Send + Sync, so a non-Send custom pointer is rejected at the message’s impl Message, just less locally.

§Caveat

A custom inline pointer (e.g. SmallBox) inflates the parent struct by its inline-storage size for every such field. The built-in Inline<T> default is recursion-aware and is the intended blanket; reserve custom inline pointers for per-field or per-prefix overrides.

§JSON serialization

When JSON codegen is enabled, custom pointers do not need serde::Serialize or serde::Deserialize. Singular message fields use MessageField’s generic serde implementation, and message-valued oneof variants serialize the pointee through this trait’s Deref bound.

§Examples

A minimal crate-local newtype wrapping a foreign pointer (the Clone derive is only needed if the enclosing message derives Clone):

ⓘ
#[derive(Clone)]
pub struct SmallBox<T>(pub smallbox::SmallBox<T, smallbox::space::S4>);

impl<T> core::ops::Deref for SmallBox<T> {
    type Target = T;
    fn deref(&self) -> &T { &self.0 }
}
impl<T> core::ops::DerefMut for SmallBox<T> {
    fn deref_mut(&mut self) -> &mut T { &mut self.0 }
}
impl<T> buffa::ProtoBox<T> for SmallBox<T> {
    fn new(value: T) -> Self { SmallBox(smallbox::smallbox!(value)) }
    fn into_inner(self) -> T { self.0.into_inner() }
}

Then point a field at it: box_type_custom("::my_crate::SmallBox<*>").

Required Methods§

Source

fn new(value: T) -> Self

Box a freshly-decoded or constructed message value.

Source

fn into_inner(self) -> T

Unwrap the pointer, returning the owned message value (the take / into_option path).

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementations on Foreign Types§

Source§

impl<T> ProtoBox<T> for Box<T>

Source§

fn new(value: T) -> Self

Source§

fn into_inner(self) -> T

Implementors§

Source§

impl<T> ProtoBox<T> for Inline<T>