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§
Sourcefn into_inner(self) -> T
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".