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
impl Payload
Sourcepub fn zero_copy(sample: Sample) -> Self
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.
Sourcepub fn from_batch(batch: RecordBatch) -> Result<Self>
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.
Sourcepub const fn kind(&self) -> PayloadKind
pub const fn kind(&self) -> PayloadKind
Which plane this payload came in on.
Sourcepub const fn is_zero_copy(&self) -> bool
pub const fn is_zero_copy(&self) -> bool
Whether reading this payload copies nothing.
Sourcepub fn address(&self) -> usize
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.
Sourcepub fn is_aligned_to(&self, alignment: usize) -> bool
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);Sourcepub fn detach(self) -> Self
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.
Sourcepub fn batch(&self) -> Result<&RecordBatch>
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).
Sourcepub fn into_batch(self) -> Result<RecordBatch>
pub fn into_batch(self) -> Result<RecordBatch>
Sourcepub fn column(&self) -> Result<&ArrayRef>
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.
Sourcepub fn schema_hash(&self) -> Result<SchemaHash>
pub fn schema_hash(&self) -> Result<SchemaHash>
Sourcepub fn view<T: FromPayload>(&self) -> Result<T>
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);Sourcepub fn sequence(&self) -> Option<u64>
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.
Sourcepub fn slot(&self) -> Option<SlotLocation>
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());Sourcepub fn slot_metadata(&self) -> Option<&[u8]>
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.