pub struct RawOutput { /* private fields */ }Expand description
An untyped publishing handle for one of the node’s outputs.
Implementations§
Source§impl RawOutput
impl RawOutput
Sourcepub fn send_arrow<A>(
&mut self,
value: &A,
metadata: Metadata,
) -> ArrowSendResult<()>
Available on crate feature arrow-interop only.
pub fn send_arrow<A>( &mut self, value: &A, metadata: Metadata, ) -> ArrowSendResult<()>
arrow-interop only.Publishes an arrow-rs value (blueprint §9.1’s send_arrow).
A is any type astrs-data’s arrow-interop bridge can convert into
a RecordBatch — in practice arrow_array::RecordBatch. See the
module docs for why the bound is written that way instead of
naming the arrow type.
§Errors
ArrowSendError::Interop when the arrow value’s layout has no AstRS
counterpart, ArrowSendError::Send for whatever
RawOutput::send_batch reports.
Source§impl RawOutput
impl RawOutput
Sourcepub fn new(shared: Arc<SessionShared>, id: DataId) -> Self
pub fn new(shared: Arc<SessionShared>, id: DataId) -> Self
A handle for id on shared.
Sourcepub fn plane(&self) -> RoutePlane
pub fn plane(&self) -> RoutePlane
The plane this output is publishing on right now (§6.3).
Sourcepub const fn segment(&self) -> Option<&ShmSegmentSpec>
pub const fn segment(&self) -> Option<&ShmSegmentSpec>
The segment this output publishes into, once upgraded.
Sourcepub fn zero_copy_threshold(&self) -> u64
pub fn zero_copy_threshold(&self) -> u64
The byte count at or above which a payload takes the zero-copy plane.
Sourcepub fn refresh(&mut self)
pub fn refresh(&mut self)
Applies any pending route change (§6.3).
Called before every publish; also public so a node can observe a transition at a moment of its choosing.
Sourcepub fn send_bytes(
&mut self,
bytes: impl AsRef<[u8]>,
metadata: Metadata,
) -> Result<()>
pub fn send_bytes( &mut self, bytes: impl AsRef<[u8]>, metadata: Metadata, ) -> Result<()>
Publishes raw payload bytes, which must already be an Arrow IPC stream (§6.1).
§Errors
NodeError::PayloadTooLarge over the negotiated frame budget,
NodeError::DaemonGone once the session has ended, and
NodeError::UnknownOutput after RawOutput::close.
Sourcepub fn send_batch(
&mut self,
batch: &RecordBatch,
metadata: Metadata,
) -> Result<()>
pub fn send_batch( &mut self, batch: &RecordBatch, metadata: Metadata, ) -> Result<()>
Encodes and publishes a record batch (§6.1).
§Errors
NodeError::Ipc when the batch cannot be encoded, plus whatever
RawOutput::send_bytes reports.
Sourcepub fn send_array(&mut self, array: ArrayRef, metadata: Metadata) -> Result<()>
pub fn send_array(&mut self, array: ArrayRef, metadata: Metadata) -> Result<()>
Publishes one column as a whole payload (§6.1’s single-payload-column convention).
The shorthand behind blueprint §9.1’s send_arrow(ArrayRef) for a
caller that already holds a single ArrayRef — including one an
arrow-rs array became through
astrs_data::interop::from_arrow_array, which is how an
arrow_array::ArrayRef reaches this output without this crate
depending on arrow-rs (see arrow’s module docs). Unfeatured,
because nothing about it needs the bridge.
§Errors
Sourcepub fn send_slice(&mut self, bytes: &[u8], metadata: Metadata) -> Result<()>
pub fn send_slice(&mut self, bytes: &[u8], metadata: Metadata) -> Result<()>
Publishes an already-encoded payload.
The one place both planes meet: everything above funnels here.
§Errors
Sourcepub fn allocate(&mut self, len: usize) -> Result<OutputSample<'_>>
pub fn allocate(&mut self, len: usize) -> Result<OutputSample<'_>>
Reserves len bytes to write into, without copying (§9.1).
On the zero-copy plane the returned buffer is the ring slot; on the
daemon path it is an owned heap buffer that the same
OutputSample::send publishes inline. A node therefore writes one
code path and gets the best plane available at that instant.
§Errors
NodeError::PayloadTooLarge over the frame budget, and
NodeError::UnknownOutput after RawOutput::close.
Sourcepub fn close(&mut self) -> Result<()>
pub fn close(&mut self) -> Result<()>
Tells the daemon this output will produce nothing further, as a
deliberate call from a node that goes on running (§7.3
NodeRequest::OutputDone).
Idempotent.
§What the daemon does with it, and why the spelling matters
OutputDone is what blueprint §12 calls an explicit output-close on a
live process: the daemon tells this port’s consumers
ProducerFinished at once, because nothing about the call predicts the
node’s exit and making a live graph wait for one would stall it.
RawOutput::drop deliberately does not use this spelling — see
its own documentation.
§Errors
NodeError::DaemonGone once the session has ended.
Sourcepub const fn is_closed(&self) -> bool
pub const fn is_closed(&self) -> bool
Whether RawOutput::close has been called.
Sourcepub fn metadata(&self) -> Metadata
pub fn metadata(&self) -> Metadata
A fresh metadata block stamped with this node’s clock (§4.3).
Sourcepub fn session(&self) -> &Arc<SessionShared> ⓘ
pub fn session(&self) -> &Arc<SessionShared> ⓘ
The session this output publishes through.
Trait Implementations§
Source§impl Drop for RawOutput
impl Drop for RawOutput
Source§fn drop(&mut self)
fn drop(&mut self)
Closing an output on drop is what makes a node that simply returns
from main produce an InputClosed downstream rather than a
mysterious silence.
It sends NodeRequest::CloseOutputs rather than
NodeRequest::OutputDone, and the difference is not cosmetic. A
handle that is going away because its owner is going away carries no
evidence about how the process ends: a node that publishes, returns
from main and exits non-zero drops this handle first, and calling
that “the producer finished” tells every consumer the opposite of what
happened. §12’s rule is written on exactly this distinction — the
daemon holds a teardown closure until the reap resolves the exit
status, and then closes with ProducerCrashed or ProducerFinished
accordingly. Sending the explicit spelling here would make
ProducerCrashed unreachable for every node that closes on the way
out, which is every node written in the §9.1 style.