Skip to main content

Payload

Struct Payload 

Source
pub struct Payload { /* private fields */ }
Expand description

One message’s payload: raw Arrow IPC bytes plus a decode cached on demand.

Implementations§

Source§

impl Payload

Source

pub fn inline(bytes: Vec<u8>) -> Self

A payload over bytes this process owns.

Source

pub fn empty() -> Self

An empty payload.

Source

pub fn zero_copy(sample: Sample) -> Self

A payload over a pinned shared-memory slot (§6.2).

The slot stays pinned — and therefore unavailable to the producer — until this payload is dropped or Payload::detached.

Source

pub fn from_batch(batch: RecordBatch) -> Result<Self>

A payload holding an already-decoded batch, for a node that produced one locally (the testing harness, the replay node).

§Errors

NodeError::Data when the batch cannot be encoded, which is what keeps Payload::bytes total for every payload however it was built.

Source

pub const fn kind(&self) -> PayloadKind

Which plane this payload came in on.

Source

pub const fn is_zero_copy(&self) -> bool

Whether reading this payload copies nothing.

Source

pub fn bytes(&self) -> &[u8] ⓘ

The raw Arrow IPC bytes, without decoding anything.

Source

pub fn len(&self) -> usize

How many bytes the payload holds.

Source

pub fn is_empty(&self) -> bool

Whether the payload is empty.

Source

pub fn address(&self) -> usize

The payload’s base address, for a caller that wants to assert the §6.1 128-byte alignment contract itself.

Source

pub fn is_aligned_to(&self, alignment: usize) -> bool

Whether the payload’s base address satisfies alignment.

§Examples
use astrs_node_api::Payload;

// An inline payload makes no alignment promise; a zero-copy one does.
let payload = Payload::empty();
let _ = payload.is_aligned_to(128);
Source

pub fn to_vec(&self) -> Vec<u8> ⓘ

Copies the bytes out.

Source

pub fn detach(self) -> Self

Releases any shared-memory slot, copying the bytes into this process.

A no-op for an inline payload. Call this before stashing a payload beyond the event that delivered it: a pinned slot the producer cannot reclaim is the one way a well-behaved consumer can stall a ring.

The decoded batch, if one was cached, survives — it never pointed into the mapping in the first place, since decoding copies buffers into aligned owned memory.

Source

pub fn batch(&self) -> Result<&RecordBatch>

The decoded record batch, decoding on the first call only.

§Errors

NodeError::Data when the bytes are not a valid one-batch Arrow IPC stream (§6.1).

Source

pub fn into_batch(self) -> Result<RecordBatch>

The decoded batch, consuming the payload and releasing any slot.

§Errors

As Payload::batch.

Source

pub fn column(&self) -> Result<&ArrayRef>

The single top-level "data" column of the payload (§6.1).

§Errors

NodeError::Data when the payload does not decode, or carries no column at all.

Source

pub fn num_rows(&self) -> Result<usize>

How many rows the payload’s batch holds.

§Errors

As Payload::batch.

Source

pub fn schema_hash(&self) -> Result<SchemaHash>

The payload’s schema fingerprint (§6.1), for cheap type-drift detection.

§Errors

As Payload::batch.

Source

pub fn view<T: FromPayload>(&self) -> Result<T>

Reads the payload as a typed value (§9.1 data.view()?).

§Errors

NodeError::Data when the payload does not decode, or when its columnar layout is not the one T expects.

§Examples
use astrs_node_api::message::{AstrsMessage, Scalar};
use astrs_node_api::Payload;

let payload = Payload::from_batch(Scalar::from(42_i64).to_record_batch()?)?;
assert_eq!(payload.view::<Scalar<i64>>()?.into_inner(), 42);
Source

pub fn sequence(&self) -> Option<u64>

The sequence number of the ring slot this payload occupies, when it came in on the zero-copy plane.

Source

pub fn slot(&self) -> Option<SlotLocation>

Where this payload sits in its ring, when it came in on the zero-copy plane (§6.2).

None for an inline payload, which sits in this process’s heap and has no slot at all.

§Examples
use astrs_node_api::Payload;

// An inline payload occupies no ring slot.
assert!(Payload::empty().slot().is_none());
Source

pub fn slot_metadata(&self) -> Option<&[u8]>

The metadata bytes that rode beside a zero-copy payload in its slot.

None for an inline payload, whose metadata travelled in the frame as a decoded astrs_wire::Metadata instead.

Trait Implementations§

Source§

impl AsRef<[u8]> for Payload

Source§

fn as_ref(&self) -> &[u8] ⓘ

Converts this type into a shared reference of the (usually inferred) input type.
Source§

impl Debug for Payload

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Display for Payload

Source§

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

Formats the value using the given formatter. Read more
Source§

impl From<Sample> for Payload

Source§

fn from(sample: Sample) -> Self

Converts to this type from the input type.
Source§

impl From<Vec<u8>> for Payload

Source§

fn from(bytes: Vec<u8>) -> Self

Converts to this type from the input type.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> MaybeDebug for T

Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToString for T
where T: Display + ?Sized,

Source§

fn to_string(&self) -> String

Converts the given value to a String. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more