#[cfg(feature = "arrow-interop")]
#[cfg_attr(docsrs, doc(cfg(feature = "arrow-interop")))]
pub mod arrow;
pub mod sample;
pub mod typed;
use std::sync::Arc;
use astrs_data::ipc::encode_payload;
use astrs_data::{ArrayRef, RecordBatch};
use astrs_shm::Producer;
use astrs_wire::{DataId, Metadata, NodeRequest, OutputPayload, PortRef, ShmSegmentSpec};
use crate::error::{NodeError, Result};
use crate::session::SessionShared;
use crate::session::routes::{RoutePlane, RouteSlot, RouteUpdate};
#[cfg(feature = "arrow-interop")]
#[cfg_attr(docsrs, doc(cfg(feature = "arrow-interop")))]
pub use arrow::{ArrowSendError, ArrowSendResult};
pub use sample::{OutputSample, SampleBuffer};
pub use typed::Output;
pub struct RawOutput {
shared: Arc<SessionShared>,
id: DataId,
slot: Arc<RouteSlot>,
producer: Option<Producer>,
segment: Option<ShmSegmentSpec>,
consumers: Vec<PortRef>,
closed: bool,
}
impl core::fmt::Debug for RawOutput {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
f.debug_struct("RawOutput")
.field("id", &self.id)
.field("plane", &self.plane())
.field("consumers", &self.consumers.len())
.field("closed", &self.closed)
.finish_non_exhaustive()
}
}
impl RawOutput {
#[must_use]
pub fn new(shared: Arc<SessionShared>, id: DataId) -> Self {
let slot = shared.routes.slot(&id);
Self {
shared,
id,
slot,
producer: None,
segment: None,
consumers: Vec::new(),
closed: false,
}
}
#[must_use]
pub const fn id(&self) -> &DataId {
&self.id
}
#[must_use]
pub fn plane(&self) -> RoutePlane {
if self.producer.is_some() {
RoutePlane::Shm
} else {
RoutePlane::Daemon
}
}
#[must_use]
pub const fn segment(&self) -> Option<&ShmSegmentSpec> {
self.segment.as_ref()
}
#[must_use]
pub fn consumers(&self) -> &[PortRef] {
&self.consumers
}
#[must_use]
pub fn zero_copy_threshold(&self) -> u64 {
self.shared.zero_copy_threshold
}
pub fn refresh(&mut self) {
match self.slot.take() {
RouteUpdate::Idle => {}
RouteUpdate::Upgrade {
producer,
segment,
consumers,
} => {
self.producer = Some(*producer);
self.segment = Some(segment);
self.consumers = consumers;
self.slot.set_plane(RoutePlane::Shm);
}
RouteUpdate::Downgrade { .. } => {
self.producer = None;
self.segment = None;
self.consumers.clear();
self.slot.set_plane(RoutePlane::Daemon);
}
}
}
pub fn send_bytes(&mut self, bytes: impl AsRef<[u8]>, metadata: Metadata) -> Result<()> {
self.send_slice(bytes.as_ref(), metadata)
}
pub fn send_batch(&mut self, batch: &RecordBatch, metadata: Metadata) -> Result<()> {
let encoded = encode_payload(batch)?;
self.send_slice(encoded.as_slice(), metadata)
}
pub fn send_array(&mut self, array: ArrayRef, metadata: Metadata) -> Result<()> {
self.send_batch(&RecordBatch::from_payload(array), metadata)
}
pub fn send_slice(&mut self, bytes: &[u8], metadata: Metadata) -> Result<()> {
self.check_open()?;
self.check_size(bytes.len())?;
self.refresh();
if self.should_use_shm(bytes.len())
&& let Some(payload) = self.write_into_slot(bytes, &metadata)?
{
self.shared.count_zero_copy_send();
return self.publish(payload, metadata);
}
self.shared.count_inline_send();
self.publish(OutputPayload::inline(bytes.to_vec()), metadata)
}
pub fn allocate(&mut self, len: usize) -> Result<OutputSample<'_>> {
self.check_open()?;
self.check_size(len)?;
self.refresh();
let shared = Arc::clone(&self.shared);
let id = self.id.clone();
let segment = self
.segment
.as_ref()
.map(|segment| (segment.name.clone(), segment.generation));
if self.should_use_shm(len)
&& let Some(producer) = self.producer.as_mut()
{
match producer.try_allocate(len) {
Ok(window) => {
return Ok(OutputSample::shm(window, shared, id, segment));
}
Err(_) => {
shared.count_shm_fallback();
}
}
}
Ok(OutputSample::heap(vec![0; len], shared, id))
}
pub fn close(&mut self) -> Result<()> {
let request = NodeRequest::OutputDone {
output: self.id.clone(),
};
self.close_with(request)
}
fn close_on_drop(&mut self) -> Result<()> {
let request = NodeRequest::CloseOutputs {
outputs: vec![self.id.clone()],
};
self.close_with(request)
}
fn close_with(&mut self, request: NodeRequest) -> Result<()> {
if self.closed {
return Ok(());
}
self.closed = true;
if let Some(producer) = self.producer.as_mut() {
producer.close();
}
self.producer = None;
self.slot.set_plane(RoutePlane::Daemon);
self.shared.send_request(request)
}
#[must_use]
pub const fn is_closed(&self) -> bool {
self.closed
}
#[must_use]
pub fn metadata(&self) -> Metadata {
Metadata::new(self.shared.hlc_now())
}
#[must_use]
pub fn session(&self) -> &Arc<SessionShared> {
&self.shared
}
fn should_use_shm(&self, len: usize) -> bool {
self.producer.is_some() && len as u64 >= self.shared.zero_copy_threshold
}
fn write_into_slot(
&mut self,
bytes: &[u8],
metadata: &Metadata,
) -> Result<Option<OutputPayload>> {
let Some((name, generation)) = self
.segment
.as_ref()
.map(|segment| (segment.name.clone(), segment.generation))
else {
return Ok(None);
};
let meta_bytes = encode_metadata(metadata)?;
let Some(producer) = self.producer.as_mut() else {
return Ok(None);
};
let mut window = match producer.try_allocate(bytes.len()) {
Ok(window) => window,
Err(_) => {
self.shared.count_shm_fallback();
return Ok(None);
}
};
let slot = window.slot_index();
window.as_mut_slice().copy_from_slice(bytes);
match window.commit(&meta_bytes) {
Ok(_seq) => Ok(Some(OutputPayload::Shm {
segment: name,
slot,
len: bytes.len() as u64,
generation,
})),
Err(_) => {
self.shared.count_shm_fallback();
Ok(None)
}
}
}
fn publish(&self, payload: OutputPayload, metadata: Metadata) -> Result<()> {
self.shared.send_request(NodeRequest::SendMessage {
output: self.id.clone(),
metadata,
payload,
})
}
fn check_open(&self) -> Result<()> {
if self.closed {
return Err(NodeError::UnknownOutput {
output: self.id.clone(),
});
}
if self.shared.is_closed() {
return Err(NodeError::DaemonGone);
}
Ok(())
}
fn check_size(&self, len: usize) -> Result<()> {
let max = self
.shared
.limits
.max_payload_bytes()
.min(astrs_data::MAX_PAYLOAD_BYTES);
if len > max {
return Err(NodeError::PayloadTooLarge { len, max });
}
Ok(())
}
}
impl Drop for RawOutput {
fn drop(&mut self) {
let _ = self.close_on_drop();
}
}
pub fn encode_metadata(metadata: &Metadata) -> Result<Vec<u8>> {
use astrs_wire::WireEncode;
Ok(metadata.encode_to_vec()?)
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
use crate::events::{Event, EventSource, QueuedEvent};
use crate::payload::Payload;
use crate::runtime::NodeRuntime;
use crate::session::{OUTGOING_CAPACITY, Outgoing};
use astrs_data::array::{Float64Array, IntoArrayRef};
use astrs_time::HlcTimestamp;
use astrs_wire::{
DataflowId, DurationMs, FrameLimits, InputSpec, NodeId, NodeSource, NodeSpawnSpec,
OutputSpec, SessionId,
};
use tokio::sync::mpsc;
fn session() -> (Arc<SessionShared>, mpsc::Receiver<Outgoing>) {
let (sender, receiver) = mpsc::channel(OUTGOING_CAPACITY);
let spec = Arc::new(
NodeSpawnSpec::new(
DataflowId::from_u128(1),
NodeId::new("camera").unwrap(),
0,
NodeSource::Dynamic,
)
.with_output(OutputSpec::new(DataId::new("image").unwrap())),
);
let shared = Arc::new(SessionShared::new(
spec,
SessionId::from_u128(1),
sender,
Arc::new(EventSource::new()),
NodeRuntime::acquire().unwrap(),
4096,
FrameLimits::uds(),
));
(shared, receiver)
}
fn output(shared: &Arc<SessionShared>) -> RawOutput {
RawOutput::new(Arc::clone(shared), DataId::new("image").unwrap())
}
fn take_send(receiver: &mut mpsc::Receiver<Outgoing>) -> (Metadata, OutputPayload) {
loop {
let Ok(Outgoing::Request(request)) = receiver.try_recv() else {
panic!("expected a request");
};
if let NodeRequest::SendMessage {
metadata, payload, ..
} = *request
{
return (metadata, payload);
}
}
}
#[test]
fn a_publish_finishes_an_open_deadline_measurement() {
let (shared, mut receiver) = session();
let mut spec = InputSpec::new(
DataId::new("frames").unwrap(),
PortRef::from_parts("upstream", "frames").unwrap(),
);
spec.deadline = Some(DurationMs::new(0));
shared.source.register_input(&spec).unwrap();
shared.source.push_input(
&spec.id,
QueuedEvent::Input {
source: PortRef::from_parts("upstream", "frames").unwrap(),
metadata: Metadata::new(HlcTimestamp::new(1, 0)),
payload: Payload::inline(vec![9]),
},
);
assert!(
shared.source.try_next().unwrap().is_input(),
"the input opened a measurement"
);
assert_eq!(shared.source.stats().deadline_violations, 0, "not yet");
let mut out = output(&shared);
out.send_bytes(vec![1, 2, 3], out.metadata()).unwrap();
let _ = take_send(&mut receiver);
assert_eq!(
shared.source.stats().deadline_violations,
1,
"the publish above must have finished the open measurement"
);
let event = shared
.source
.try_next()
.expect("the violation reached the control lane");
assert!(matches!(event, Event::Error(_)), "{event:?}");
}
#[test]
fn a_publish_with_no_open_deadline_is_unaffected() {
let (shared, mut receiver) = session();
let mut out = output(&shared);
out.send_bytes(vec![1, 2, 3], out.metadata()).unwrap();
let _ = take_send(&mut receiver);
assert_eq!(shared.source.stats().deadline_violations, 0);
}
#[test]
fn a_fresh_output_publishes_on_the_daemon_path() {
let (shared, mut receiver) = session();
let mut out = output(&shared);
assert_eq!(out.plane(), RoutePlane::Daemon);
assert_eq!(out.id().as_str(), "image");
assert!(out.segment().is_none());
assert!(out.consumers().is_empty());
assert_eq!(out.zero_copy_threshold(), 4096);
out.send_bytes(vec![1, 2, 3], out.metadata()).unwrap();
let (_, payload) = take_send(&mut receiver);
assert_eq!(payload.bytes(), Some(&[1, 2, 3][..]));
assert_eq!(shared.stats().sends_inline, 1);
}
#[test]
fn a_record_batch_is_encoded_before_it_is_sent() {
let (shared, mut receiver) = session();
let mut out = output(&shared);
let batch =
RecordBatch::from_payload(Float64Array::from_values([1.0, 2.0]).into_array_ref());
out.send_batch(&batch, out.metadata()).unwrap();
let (_, payload) = take_send(&mut receiver);
let bytes = payload.bytes().unwrap();
let decoded = astrs_data::ipc::decode_payload(bytes).unwrap();
assert_eq!(decoded, batch);
}
#[test]
fn allocate_falls_back_to_the_heap_without_a_producer() {
let (shared, mut receiver) = session();
let mut out = output(&shared);
let mut sample = out.allocate(8).unwrap();
assert_eq!(sample.len(), 8);
assert!(!sample.is_zero_copy());
sample.as_mut_slice().copy_from_slice(&[7; 8]);
let metadata = Metadata::new(shared.hlc_now());
sample.send(metadata).unwrap();
let (_, payload) = take_send(&mut receiver);
assert_eq!(payload.bytes(), Some(&[7; 8][..]));
}
#[test]
fn an_oversized_payload_is_refused_before_it_is_copied() {
let (shared, _receiver) = session();
let mut out = output(&shared);
let max = shared
.limits
.max_payload_bytes()
.min(astrs_data::MAX_PAYLOAD_BYTES);
let error = out.check_size(max + 1).unwrap_err();
assert!(matches!(error, NodeError::PayloadTooLarge { .. }));
assert!(out.allocate(max + 1).is_err());
}
#[test]
fn closing_is_idempotent_and_refuses_later_sends() {
let (shared, mut receiver) = session();
let mut out = output(&shared);
out.close().unwrap();
out.close().unwrap();
assert!(out.is_closed());
let error = out.send_bytes(vec![1], Metadata::default()).unwrap_err();
assert!(matches!(error, NodeError::UnknownOutput { .. }));
let mut closes = 0;
while let Ok(Outgoing::Request(request)) = receiver.try_recv() {
if matches!(*request, NodeRequest::OutputDone { .. }) {
closes += 1;
}
}
assert_eq!(closes, 1, "one OutputDone, however many close() calls");
}
#[test]
fn dropping_an_output_closes_it_as_a_teardown() {
let (shared, mut receiver) = session();
let id = output(&shared).id.clone();
drop(output(&shared));
let Ok(Outgoing::Request(request)) = receiver.try_recv() else {
panic!("expected a request");
};
match &*request {
NodeRequest::CloseOutputs { outputs } => assert_eq!(outputs, &[id]),
other => panic!("expected CloseOutputs, got {other:?}"),
}
}
#[test]
fn an_explicit_close_stays_an_output_done() {
let (shared, mut receiver) = session();
let mut out = output(&shared);
out.close().unwrap();
let Ok(Outgoing::Request(request)) = receiver.try_recv() else {
panic!("expected a request");
};
assert!(matches!(*request, NodeRequest::OutputDone { .. }));
}
#[test]
fn a_closed_session_refuses_publishing() {
let (shared, _receiver) = session();
let mut out = output(&shared);
shared.close();
assert!(matches!(
out.send_bytes(vec![1], Metadata::default()),
Err(NodeError::DaemonGone)
));
}
#[test]
fn a_route_downgrade_is_picked_up_on_the_next_publish() {
let (shared, _receiver) = session();
let mut out = output(&shared);
shared
.routes
.slot(&DataId::new("image").unwrap())
.offer_downgrade(astrs_wire::RouteDowngradeReason::ConsumerDetached {
consumer: PortRef::from_parts("detect", "frames").unwrap(),
});
out.refresh();
assert_eq!(out.plane(), RoutePlane::Daemon);
assert!(out.segment().is_none());
}
#[test]
fn metadata_is_stamped_with_the_node_clock() {
let (shared, _receiver) = session();
let out = output(&shared);
let first = out.metadata();
let second = out.metadata();
assert!(second.timestamp >= first.timestamp);
assert!(format!("{out:?}").contains("image"));
}
#[test]
fn metadata_encodes_for_a_slot() {
let metadata = Metadata::default();
assert!(!encode_metadata(&metadata).unwrap().is_empty());
}
}