pub trait ProtoList<T>:
Default
+ Clone
+ PartialEq
+ Debug
+ Send
+ Sync
+ FromIterator<T>
+ From<Vec<T>>
+ Deref<Target = [T]> {
// Required methods
fn push(&mut self, value: T);
fn clear(&mut self);
// Provided method
fn reserve(&mut self, additional: usize) { ... }
}Expand description
The owned collection type backing a proto repeated field.
The default is Vec<T>; buffa_build’s repeated_type_custom knob
substitutes any type that implements ProtoList<T> — for example a
SmallVec-backed inline collection that avoids a heap allocation for short
repeated fields. The wire format is identical regardless of the collection;
only the in-memory owned type changes, and view types keep borrowing
&[T].
There is intentionally no blanket impl — the built-in Vec<T> impl below is
the only one buffa provides. Because ProtoList is a buffa-owned trait, a
foreign collection (e.g. smallvec::SmallVec) cannot implement it
directly (orphan rule). Always wrap a foreign collection in a crate-local
newtype and implement ProtoList on the newtype, exactly like the
ProtoString newtype pattern (see examples/custom-types in the buffa
repository). This holds
even for binary-only builds — the generated decode/clear paths require
Field: ProtoList.
§Contract
- The collection must be growable:
pushis infallible (notry_push), so the decoder appends one element per wire element with no way to reject an oversized field. A truly capacity-bounded collection (e.g. a fixed-capacityArrayVec) will panic on input larger than its capacity rather than return a decode error — do not use one as aProtoList.SmallVecis fine because it spills to the heap. - The supertraits and methods must agree on contents:
pushappends one element in order,Deref<Target = [T]>exposes the elements as a slice in that same order (the encode andcompute_sizepaths iterate it),FromIteratorrebuilds the collection for the view→owned conversion,From<Vec<T>>is the ergonomic constructor for building a field by hand (vec![..].into(), mirroringProtoBytes’sFrom<Vec<u8>>), andDefaultproduces the empty collection (the field’s cleared state). - A generic newtype’s
Defaultmust be hand-written (not#[derive]d), or the derive forces a spuriousT: Defaultbound; expect aclippy::derivable_implslint there and#[allow]it (see the example).
§Limitations (for a custom collection)
- Reflection / vtable: a collection used under the reflection or vtable
path must implement
buffa_descriptor’sReflectList. It is not derivable, but aVec-backed newtype can delegate all three methods to the innerVec<T>: ReflectListimpl (which requiresT: ReflectElement). - JSON / connectrpc: a collection used in a JSON-enabled build must
implement
serde::Serialize/Deserialize(its own impls, or the newtype’s). Note that frameworks built on buffa may require the message’s serde derive unconditionally — for exampleconnectrpcbounds its handler and client message types onSerialize/DeserializeOwnedeven when JSON is never used at runtime — so a custom collection used through such a framework must be serde-capable regardless. arbitrary: under thearbitraryfeature a collection must implementarbitrary::Arbitrary(trivially derivable on a newtype). Not needed on a field whose element is a custom string type or a non-default bytes type: generated code builds that field throughFrom<Vec<T>>.
§Examples
A minimal crate-local newtype wrapping smallvec::SmallVec for binary use:
#[derive(Clone, PartialEq, Debug)]
pub struct SmallList<T>(pub smallvec::SmallVec<[T; 4]>);
// Hand-written so it does not require `T: Default`.
#[allow(clippy::derivable_impls)]
impl<T> Default for SmallList<T> {
fn default() -> Self { SmallList(smallvec::SmallVec::new()) }
}
impl<T> core::ops::Deref for SmallList<T> {
type Target = [T];
fn deref(&self) -> &[T] { &self.0 }
}
impl<T> FromIterator<T> for SmallList<T> {
fn from_iter<I: IntoIterator<Item = T>>(it: I) -> Self {
SmallList(smallvec::SmallVec::from_iter(it))
}
}
impl<T> From<Vec<T>> for SmallList<T> { // enables `vec![..].into()`
fn from(v: Vec<T>) -> Self { SmallList(smallvec::SmallVec::from_vec(v)) }
}
impl<T: Clone + PartialEq + core::fmt::Debug + Send + Sync> buffa::ProtoList<T>
for SmallList<T>
{
fn push(&mut self, v: T) { self.0.push(v); }
fn clear(&mut self) { self.0.clear(); }
// reserve left as the advisory no-op default, so a byte-count hint
// never spills the inline storage.
}Then point a field at it: repeated_type_custom("::my_crate::SmallList<*>").
Required Methods§
Provided Methods§
Sourcefn reserve(&mut self, additional: usize)
fn reserve(&mut self, additional: usize)
Best-effort capacity hint from the packed-scalar decoder, sized in elements.
This is advisory: the default implementation does nothing, so a
bounded inline collection is never forced to pre-allocate (or spill its
inline storage) from an attacker-influenced length prefix. The built-in
Vec<T> impl overrides it to call Vec::reserve. The decoder invokes
it through the trait (so an inherent reserve on the collection does not
shadow this advisory contract); decoders may pass a loose upper bound, so
never rely on the requested capacity being honored.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".