Struct Buffer 

pub struct Buffer { /* private fields */ }

A reusable row buffer.

For ILP senders this exposes the existing byte-oriented buffer implementation. For QWP/UDP senders it dispatches to the QWP-specific row buffer.

Implementations

impl Buffer

pub fn new(protocol_version: ProtocolVersion) -> Self

Creates a new ILP buffer with default parameters.

pub fn with_max_name_len( protocol_version: ProtocolVersion, max_name_len: usize, ) -> Self

Creates a new ILP buffer with a custom maximum name length.

pub fn with_init_capacity_and_max_name_len( protocol_version: ProtocolVersion, init_capacity: usize, max_name_len: usize, ) -> Self

Creates a new ILP buffer that pre-allocates its byte storage to init_capacity and accepts table / column names up to max_name_len. The buffer is allowed to grow past init_capacity; it is purely a starting-size hint to avoid early reallocations.

pub fn new_qwp() -> Self

pub fn qwp_with_max_name_len(max_name_len: usize) -> Self

Like Buffer::new_qwp with an explicit maximum name length.

pub fn new_qwp_ws() -> Self

Creates a new QWP/WebSocket columnar buffer with a 127-byte name length limit. Accepts the row-by-row table / symbol / column_* / at API; consumed by Sender::flush.

pub fn qwp_ws_with_max_name_len(max_name_len: usize) -> Self

Like Buffer::new_qwp_ws with an explicit maximum name length.

pub fn protocol_version(&self) -> ProtocolVersion

Returns the protocol version associated with this buffer.

For ILP buffers this is the ILP protocol version. For QWP/UDP buffers this is the QWP datagram version, currently represented as ProtocolVersion::V1. Interpret the value together with the buffer transport; do not use it by itself for ILP feature gating.

pub fn reserve(&mut self, additional: usize)

Reserves capacity associated with additional more bytes of buffered data.

For ILP buffers this reserves exact serialized-byte capacity. For QWP/UDP buffers this is a heuristic prewarm of the internal arenas and planner scratch used during datagram planning and encoding; it is not an exact guarantee that Buffer::len can grow by additional bytes without further allocation.

pub fn len(&self) -> usize

Returns the current buffered size.

For ILP buffers this is the exact serialized byte count. For QWP/UDP buffers this is the size hint used for flush planning. For QWP/WebSocket buffers this is only a local size hint; symbol-ID remapping and replay dictionary state can change the eventual frame size. The sender enforces max_buf_size against the encoded replay message.

pub fn row_count(&self) -> usize

Returns the number of completed rows currently buffered.

A row is counted only after Buffer::at or Buffer::at_now completes it.

pub fn transactional(&self) -> bool

Returns whether the buffered batch is transactional.

For ILP buffers this is true only while the buffer contains rows for at most one table. QWP/UDP does not support transactional flushes, so QWP buffers always return false.

pub fn is_empty(&self) -> bool

Returns true if the buffer contains no committed or in-progress rows.

pub fn capacity(&self) -> usize

Returns the current retained-capacity hint for the buffer.

For ILP buffers, this is byte capacity. For QWP/UDP buffers, this is an implementation-defined retained-capacity hint and should not be interpreted as exact byte capacity.

pub fn as_bytes(&self) -> &[u8]

Returns the raw serialized ILP bytes currently stored in the buffer.

QWP/UDP buffers build datagrams during flush, so this returns an empty slice for QWP/UDP.

pub fn set_marker(&mut self) -> Result<()>

Marks the current buffer state so it can later be restored with Buffer::rewind_to_marker.

Setting a new marker replaces the currently stored rewind point, including one established by Buffer::bookmark.

pub fn bookmark(&mut self) -> Result<Bookmark>

Captures the current buffer state so it can later be restored with Buffer::rewind_to_bookmark.

Capturing a new bookmark replaces the previous bookmark or marker.

pub fn rewind_to_bookmark(&mut self, bookmark: Bookmark) -> Result<()>

Rewinds the buffer to the state referenced by bookmark and then clears that bookmark.

pub fn clear_bookmark(&mut self, bookmark: Bookmark)

Clears bookmark if it is still the currently active bookmark.

pub fn rewind_to_marker(&mut self) -> Result<()>

Rewinds the buffer to the currently stored rewind point and then clears it.

This may rewind a state established by either Buffer::set_marker or Buffer::bookmark.

Returns an error if no rewind point is set.

pub fn clear_marker(&mut self)

Clears the current stored rewind point, including one established by Buffer::bookmark.

pub fn clear(&mut self)

Clears the buffer contents and marker while retaining allocated capacity.

pub fn check_can_flush(&self) -> Result<()>

Validates that the buffer is ready to be flushed with crate::ingress::Sender::flush or one of its variants.

Returns an error when the current API call sequence is incomplete, such as an unfinished row.

pub fn table<'a, N>(&mut self, name: N) -> Result<&mut Self>

where N: AsRef<str> + TryInto<TableName<'a>>, Error: From<N::Error>,

Starts a new row for name.

Every row must begin with a table name. See Buffer for the full call sequence.

pub fn symbol<'a, N, S>(&mut self, name: N, value: S) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, S: AsRef<str>, Error: From<N::Error>,

Adds a symbol column to the current row.

All symbol columns must be recorded before any non-symbol columns.

When the buffer is flushed over QWP/WebSocket, every distinct symbol recorded here is interned into the same connection-scoped dictionary the column/chunk API uses — capped at 2,000,000 entries and 256 MiB of UTF-8 across the whole connection, not per buffer or per flush. Exceeding it fails the flush with SymbolDictFull, and the dictionary is only reset by retiring the connection that owns it — which a full dictionary now does automatically on return, so a pooled sender is dropped (not recycled) and the next borrow gets a fresh one. Wait / commit first if frames flushed earlier must not be lost; see SymbolDictFull for the per-API list. ILP (TCP/HTTP) flushes carry no such dictionary and are unaffected.

pub fn symbol_opt<'a, N, S>( &mut self, name: N, value: Option<S>, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, S: AsRef<str>, Error: From<N::Error>,

Adds a symbol column if value is Some; otherwise leaves the row unchanged.

See symbol for the QWP/WebSocket connection-scoped dictionary cap that applies to every symbol recorded this way.

pub fn column_bool<'a, N>(&mut self, name: N, value: bool) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds a boolean column to the current row.

pub fn column_bool_opt<'a, N>( &mut self, name: N, value: Option<bool>, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds a boolean column if value is Some; otherwise leaves the row unchanged.

pub fn column_i64<'a, N>(&mut self, name: N, value: i64) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds an integer column to the current row.

pub fn column_i64_opt<'a, N>( &mut self, name: N, value: Option<i64>, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds an integer column if value is Some; otherwise leaves the row unchanged.

pub fn column_i8<'a, N>(&mut self, name: N, value: i8) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds an 8-bit signed integer column to the current row. QWP-only.

pub fn column_i8_opt<'a, N>( &mut self, name: N, value: Option<i8>, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds an 8-bit signed integer column if value is Some. QWP-only.

pub fn column_i16<'a, N>(&mut self, name: N, value: i16) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds a 16-bit signed integer column to the current row. QWP-only.

pub fn column_i16_opt<'a, N>( &mut self, name: N, value: Option<i16>, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds a 16-bit signed integer column if value is Some. QWP-only.

pub fn column_i32<'a, N>(&mut self, name: N, value: i32) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds a 32-bit signed integer column to the current row. QWP-only.

pub fn column_i32_opt<'a, N>( &mut self, name: N, value: Option<i32>, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds a 32-bit signed integer column if value is Some. QWP-only.

pub fn column_f32<'a, N>(&mut self, name: N, value: f32) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds a 32-bit floating-point column to the current row. QWP-only.

pub fn column_f32_opt<'a, N>( &mut self, name: N, value: Option<f32>, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds a 32-bit floating-point column if value is Some. QWP-only.

pub fn column_f64<'a, N>(&mut self, name: N, value: f64) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds a floating-point column to the current row.

pub fn column_f64_opt<'a, N>( &mut self, name: N, value: Option<f64>, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds a floating-point column if value is Some; otherwise leaves the row unchanged.

pub fn column_str<'a, N, S>(&mut self, name: N, value: S) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, S: AsRef<str>, Error: From<N::Error>,

Adds a string column to the current row.

pub fn column_str_opt<'a, N, S>( &mut self, name: N, value: Option<S>, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, S: AsRef<str>, Error: From<N::Error>,

Adds a string column if value is Some; otherwise leaves the row unchanged.

pub fn column_dec<'a, N, S>(&mut self, name: N, value: S) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, S: TryInto<DecimalView<'a>>, Error: From<N::Error> + From<S::Error>,

Adds a decimal column to the current row.

Returns an error if the active protocol does not support decimal values. QWP/UDP accepts the same decimal input forms as ILP and encodes them as nullable DECIMAL256 columns on the wire.

pub fn column_dec_opt<'a, N, S>( &mut self, name: N, value: Option<S>, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, S: TryInto<DecimalView<'a>>, Error: From<N::Error> + From<S::Error>,

Adds a decimal column if value is Some; otherwise leaves the row unchanged.

pub fn column_dec64<'a, N, S>(&mut self, name: N, value: S) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, S: TryInto<DecimalView<'a>>, Error: From<N::Error> + From<S::Error>,

Adds a 64-bit decimal column to the current row. QWP-only.

The unscaled magnitude (at the column’s pinned scale) must fit a signed 64-bit integer; values that do not fit return InvalidApiCall.

pub fn column_dec64_opt<'a, N, S>( &mut self, name: N, value: Option<S>, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, S: TryInto<DecimalView<'a>>, Error: From<N::Error> + From<S::Error>,

Adds a 64-bit decimal column if value is Some. QWP-only.

pub fn column_dec128<'a, N, S>( &mut self, name: N, value: S, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, S: TryInto<DecimalView<'a>>, Error: From<N::Error> + From<S::Error>,

Adds a 128-bit decimal column to the current row. QWP-only.

The unscaled magnitude (at the column’s pinned scale) must fit a signed 128-bit integer; values that do not fit return InvalidApiCall.

pub fn column_dec128_opt<'a, N, S>( &mut self, name: N, value: Option<S>, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, S: TryInto<DecimalView<'a>>, Error: From<N::Error> + From<S::Error>,

Adds a 128-bit decimal column if value is Some. QWP-only.

pub fn column_uuid<'a, N>( &mut self, name: N, lo: u64, hi: u64, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds a UUID column to the current row. QWP-only.

Per spec, the wire encoding writes lo (8 bytes LE) followed by hi (8 bytes LE).

pub fn column_uuid_opt<'a, N>( &mut self, name: N, value: Option<(u64, u64)>, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds a UUID column if value is Some. QWP-only.

pub fn column_long256<'a, N>( &mut self, name: N, value: &[u8; 32], ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds a LONG256 column to the current row. QWP-only.

value is the wire-format byte buffer: four 64-bit limbs encoded little-endian, least-significant limb first (32 bytes total).

pub fn column_long256_opt<'a, N>( &mut self, name: N, value: Option<&[u8; 32]>, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds a LONG256 column if value is Some. QWP-only.

pub fn column_ipv4<'a, N>( &mut self, name: N, value: Ipv4Addr, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds an IPv4 column to the current row. QWP-only.

The wire encoding writes the 4 octets as u32::from(addr).to_le_bytes(), matching Rust’s natural Ipv4Addr packing (octet 0 in the high byte).

IPv4 (0x18) is part of the QWP v1 spec.

pub fn column_ipv4_opt<'a, N>( &mut self, name: N, value: Option<Ipv4Addr>, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds an IPv4 column if value is Some. QWP-only.

pub fn column_date<'a, N>(&mut self, name: N, millis: i64) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds a DATE column (milliseconds since the Unix epoch). QWP-only.

pub fn column_date_opt<'a, N>( &mut self, name: N, value: Option<i64>, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds a DATE column if value is Some. QWP-only.

pub fn column_char<'a, N>(&mut self, name: N, value: u16) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds a CHAR column (single UTF-16 code unit). QWP-only.

pub fn column_char_opt<'a, N>( &mut self, name: N, value: Option<u16>, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds a CHAR column if value is Some. QWP-only.

pub fn column_binary<'a, N>( &mut self, name: N, value: &[u8], ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds a BINARY column (opaque byte sequence). QWP-only.

BINARY (0x17) is part of the QWP v1 spec.

pub fn column_binary_opt<'a, N>( &mut self, name: N, value: Option<&[u8]>, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds a BINARY column if value is Some. QWP-only.

pub fn column_geohash<'a, N>( &mut self, name: N, bits: u64, precision_bits: u8, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds a GEOHASH column. precision_bits must be in 1..=60 and is pinned per column (subsequent rows must match). QWP-only.

pub fn column_geohash_opt<'a, N>( &mut self, name: N, value: Option<(u64, u8)>, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, Error: From<N::Error>,

Adds a GEOHASH column if value is Some. QWP-only.

pub fn column_arr<'a, N, T, D>( &mut self, name: N, view: &T, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, T: NdArrayView<D>, D: ArrayElement + ArrayElementSealed, Error: From<N::Error>,

Adds an array column to the current row.

Arrays require ILP protocol version 2 or later. QWP supports f64 (DOUBLE_ARRAY, 0x11) and i64 (LONG_ARRAY, 0x12) element types. LONG_ARRAY is part of the QWP v1 spec. Server-side ingest does not currently implement this wire type; batches using it will be rejected with a descriptive error. This may change in future server releases.

pub fn column_arr_opt<'a, N, T, D>( &mut self, name: N, value: Option<&T>, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, T: NdArrayView<D>, D: ArrayElement + ArrayElementSealed, Error: From<N::Error>,

Adds an array column if value is Some; otherwise leaves the row unchanged.

pub fn column_ts<'a, N, T>(&mut self, name: N, value: T) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, T: TryInto<Timestamp>, Error: From<N::Error> + From<T::Error>,

Adds a timestamp column to the current row.

Accepts either microsecond or nanosecond timestamps.

pub fn column_ts_opt<'a, N, T>( &mut self, name: N, value: Option<T>, ) -> Result<&mut Self>

where N: AsRef<str> + TryInto<ColumnName<'a>>, T: TryInto<Timestamp>, Error: From<N::Error> + From<T::Error>,

Adds a timestamp column if value is Some; otherwise leaves the row unchanged.

pub fn at<T>(&mut self, timestamp: T) -> Result<()>

where T: TryInto<Timestamp>, Error: From<T::Error>,

Completes the current row with a designated timestamp.

After this call you may begin the next row with Buffer::table or flush the buffer. Accepts either microsecond or nanosecond timestamps.

pub fn at_now(&mut self) -> Result<()>

Completes the current row without a designated timestamp so the server assigns one.

This is not equivalent to calling Buffer::at with the current client time.

Trait Implementations

impl Clone for Buffer

fn clone(&self) -> Buffer

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Buffer

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

Formats the value using the given formatter.