Struct RowArena 

pub struct RowArena { /* private fields */ }

RowArena is used to hold on to temporary Rows for functions like eval that need to create complex Datums but don’t have a Row to put them in yet.

Implementations

impl RowArena

pub fn new() -> Self

pub fn with_budget(budget: usize) -> Self

Creates a RowArena that reports itself RowArena::over_budget once it holds more than budget bytes.

The budget is advisory to the arena itself: pushes still succeed, because handing back a truncated value would corrupt the datum. It is the caller’s job to poll over_budget at a point where it can fail, so the bytes an arena actually reaches is budget plus whatever the operation in flight at the time added.

NOTE: a budget bounds a single ad-hoc evaluation in a shared process (see mz_adapter::webhook). It must not be given to an arena that feeds a compute dataflow. A dataflow re-evaluates the same expression against the same input and must return the same result every time. Whether an evaluation is over budget depends on what else the arena has accumulated, and the webhook budget is a runtime dyncfg, so a budgeted dataflow arena would make the result depend on when it ran. Differential then turns a changed-but-not-retracted result into non-accumulating diffs that corrupt the collection. A dataflow that ever needs a budget must fix it for the lifetime of a cluster replica.

pub fn allocated_bytes(&self) -> usize

Bytes this arena currently holds.

pub fn over_budget(&self) -> bool

Whether this arena holds more than its budget. Always false without one.

pub fn budget_remaining(&self) -> usize

Bytes this arena can still take before it is RowArena::over_budget, or usize::MAX without a budget.

Intended for an operation that can predict its own size and would rather fail than build a value it is about to be told is too big.

pub fn with_capacity(capacity: usize) -> Self

Creates a RowArena with an initial region sized to hold capacity bytes, to avoid reallocations as the first datums are created in the arena.

pub fn reserve(&self, additional: usize)

Ensures the active region can hold at least additional more bytes without allocating a new region. Call this when you expect to push roughly additional bytes next.

pub fn push_bytes<'a, B: Deref<Target = [u8]>>(&'a self, bytes: B) -> &'a [u8]

Copies bytes into the arena and returns a reference valid for its lifetime.

Accepts anything that derefs to [u8] (e.g. Vec<u8>, &[u8]); the bytes are copied, so the caller’s allocation is not retained.

pub fn push_owned_bytes<'a>(&'a self, bytes: Vec<u8>) -> &'a [u8]

Moves bytes into the arena and returns a reference valid for its lifetime.

Prefer this to RowArena::push_bytes whenever the bytes are already owned: a value large enough that it would get a region to itself has its allocation adopted as that region, rather than a fresh region being allocated and copied into, which for a large value halves the peak. Smaller values are copied, so the arena keeps bump allocating.

pub fn push_string<'a>(&'a self, string: String) -> &'a str

Moves string into the arena and returns a reference valid for its lifetime.

pub fn writer(&self) -> RowArenaBuf<'_>

Returns a growable, writeable byte buffer for assembling a value incrementally.

Write into it with RowArenaBuf::push, RowArenaBuf::extend_from_slice, or std::io::Write, then call RowArenaBuf::finish to copy the result into the arena and obtain a reference valid for the arena’s lifetime. The backing buffer is a single scratch allocation reused across writers, so this lets a producer that builds bytes piecewise (e.g. decoding a row) avoid managing its own scratch.

Nested writers are sound but not free: a writer obtained while another is still live can’t reuse the (in-use) scratch, so it allocates its own buffer. Steady-state, non-nested use stays allocation-free.

pub fn push_unary_row<'a>(&'a self, row: Row) -> Datum<'a>

Take ownership of row for the lifetime of the arena, returning a reference to the first datum in the row.

If we had an owned datum type, this method would be much clearer, and would be called push_owned_datum.

pub fn make_datum<'a, F>(&'a self, f: F) -> Datum<'a>

where F: FnOnce(&mut RowPacker<'_>),

Convenience function to make a new Row containing a single datum, and take ownership of it for the lifetime of the arena

let arena = RowArena::new();
let datum = arena.make_datum(|packer| {
  packer.push_list(&[Datum::String("hello"), Datum::String("world")]);
});
assert_eq!(datum.unwrap_list().iter().collect::<Vec<_>>(), vec![Datum::String("hello"), Datum::String("world")]);

pub fn make_datum_list<'a, T: Borrow<Datum<'a>>>( &'a self, iter: impl IntoIterator<Item = T>, ) -> DatumList<'a, T>

Convenience function to build a list datum from an iterator of typed elements and return it as a DatumList<'a, T>.

By accepting an iterator of T: Borrow<Datum> instead of a raw RowPacker closure, this guarantees that only elements of type T are pushed.

pub fn make_datum_nested<'a, F>(&'a self, f: F) -> DatumNested<'a>

where F: FnOnce(&mut RowPacker<'_>),

Convenience function identical to make_datum but instead returns a DatumNested.

pub fn try_make_datum<'a, F, E>(&'a self, f: F) -> Result<Datum<'a>, E>

where F: FnOnce(&mut RowPacker<'_>) -> Result<(), E>,

Like RowArena::make_datum, but the provided closure can return an error.

pub fn clear(&mut self)

Clear the contents of the arena.

Retains the single largest region (emptied) so the arena can be reused without reallocating; a workload that clears between uses of similar size becomes allocation-free.

Trait Implementations

impl Debug for RowArena

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

Formats the value using the given formatter.

impl Default for RowArena

fn default() -> RowArena

Returns the “default value” for a type.