1#[cfg(feature = "arrow-interop")]
40#[cfg_attr(docsrs, doc(cfg(feature = "arrow-interop")))]
41pub mod arrow;
42pub mod sample;
43pub mod typed;
44
45use std::sync::Arc;
46
47use astrs_data::ipc::encode_payload;
48use astrs_data::{ArrayRef, RecordBatch};
49use astrs_shm::Producer;
50use astrs_wire::{DataId, Metadata, NodeRequest, OutputPayload, PortRef, ShmSegmentSpec};
51
52use crate::error::{NodeError, Result};
53use crate::session::SessionShared;
54use crate::session::routes::{RoutePlane, RouteSlot, RouteUpdate};
55
56#[cfg(feature = "arrow-interop")]
57#[cfg_attr(docsrs, doc(cfg(feature = "arrow-interop")))]
58pub use arrow::{ArrowSendError, ArrowSendResult};
59pub use sample::{OutputSample, SampleBuffer};
60pub use typed::Output;
61
62pub struct RawOutput {
64 shared: Arc<SessionShared>,
66 id: DataId,
68 slot: Arc<RouteSlot>,
70 producer: Option<Producer>,
72 segment: Option<ShmSegmentSpec>,
74 consumers: Vec<PortRef>,
76 closed: bool,
78}
79
80impl core::fmt::Debug for RawOutput {
81 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
82 f.debug_struct("RawOutput")
83 .field("id", &self.id)
84 .field("plane", &self.plane())
85 .field("consumers", &self.consumers.len())
86 .field("closed", &self.closed)
87 .finish_non_exhaustive()
88 }
89}
90
91impl RawOutput {
92 #[must_use]
94 pub fn new(shared: Arc<SessionShared>, id: DataId) -> Self {
95 let slot = shared.routes.slot(&id);
96 Self {
97 shared,
98 id,
99 slot,
100 producer: None,
101 segment: None,
102 consumers: Vec::new(),
103 closed: false,
104 }
105 }
106
107 #[must_use]
109 pub const fn id(&self) -> &DataId {
110 &self.id
111 }
112
113 #[must_use]
115 pub fn plane(&self) -> RoutePlane {
116 if self.producer.is_some() {
117 RoutePlane::Shm
118 } else {
119 RoutePlane::Daemon
120 }
121 }
122
123 #[must_use]
125 pub const fn segment(&self) -> Option<&ShmSegmentSpec> {
126 self.segment.as_ref()
127 }
128
129 #[must_use]
131 pub fn consumers(&self) -> &[PortRef] {
132 &self.consumers
133 }
134
135 #[must_use]
137 pub fn zero_copy_threshold(&self) -> u64 {
138 self.shared.zero_copy_threshold
139 }
140
141 pub fn refresh(&mut self) {
146 match self.slot.take() {
147 RouteUpdate::Idle => {}
148 RouteUpdate::Upgrade {
149 producer,
150 segment,
151 consumers,
152 } => {
153 self.producer = Some(*producer);
154 self.segment = Some(segment);
155 self.consumers = consumers;
156 self.slot.set_plane(RoutePlane::Shm);
157 }
158 RouteUpdate::Downgrade { .. } => {
159 self.producer = None;
162 self.segment = None;
163 self.consumers.clear();
164 self.slot.set_plane(RoutePlane::Daemon);
165 }
166 }
167 }
168
169 pub fn send_bytes(&mut self, bytes: impl AsRef<[u8]>, metadata: Metadata) -> Result<()> {
178 self.send_slice(bytes.as_ref(), metadata)
179 }
180
181 pub fn send_batch(&mut self, batch: &RecordBatch, metadata: Metadata) -> Result<()> {
188 let encoded = encode_payload(batch)?;
189 self.send_slice(encoded.as_slice(), metadata)
190 }
191
192 pub fn send_array(&mut self, array: ArrayRef, metadata: Metadata) -> Result<()> {
207 self.send_batch(&RecordBatch::from_payload(array), metadata)
208 }
209
210 pub fn send_slice(&mut self, bytes: &[u8], metadata: Metadata) -> Result<()> {
218 self.check_open()?;
219 self.check_size(bytes.len())?;
220 self.refresh();
221
222 if self.should_use_shm(bytes.len())
223 && let Some(payload) = self.write_into_slot(bytes, &metadata)?
224 {
225 self.shared.count_zero_copy_send();
226 return self.publish(payload, metadata);
227 }
228 self.shared.count_inline_send();
229 self.publish(OutputPayload::inline(bytes.to_vec()), metadata)
230 }
231
232 pub fn allocate(&mut self, len: usize) -> Result<OutputSample<'_>> {
244 self.check_open()?;
245 self.check_size(len)?;
246 self.refresh();
247
248 let shared = Arc::clone(&self.shared);
249 let id = self.id.clone();
250 let segment = self
251 .segment
252 .as_ref()
253 .map(|segment| (segment.name.clone(), segment.generation));
254
255 if self.should_use_shm(len)
256 && let Some(producer) = self.producer.as_mut()
257 {
258 match producer.try_allocate(len) {
259 Ok(window) => {
260 return Ok(OutputSample::shm(window, shared, id, segment));
261 }
262 Err(_) => {
263 shared.count_shm_fallback();
266 }
267 }
268 }
269 Ok(OutputSample::heap(vec![0; len], shared, id))
270 }
271
272 pub fn close(&mut self) -> Result<()> {
292 let request = NodeRequest::OutputDone {
293 output: self.id.clone(),
294 };
295 self.close_with(request)
296 }
297
298 fn close_on_drop(&mut self) -> Result<()> {
307 let request = NodeRequest::CloseOutputs {
308 outputs: vec![self.id.clone()],
309 };
310 self.close_with(request)
311 }
312
313 fn close_with(&mut self, request: NodeRequest) -> Result<()> {
315 if self.closed {
316 return Ok(());
317 }
318 self.closed = true;
319 if let Some(producer) = self.producer.as_mut() {
320 producer.close();
321 }
322 self.producer = None;
323 self.slot.set_plane(RoutePlane::Daemon);
324 self.shared.send_request(request)
325 }
326
327 #[must_use]
329 pub const fn is_closed(&self) -> bool {
330 self.closed
331 }
332
333 #[must_use]
335 pub fn metadata(&self) -> Metadata {
336 Metadata::new(self.shared.hlc_now())
337 }
338
339 #[must_use]
341 pub fn session(&self) -> &Arc<SessionShared> {
342 &self.shared
343 }
344
345 fn should_use_shm(&self, len: usize) -> bool {
347 self.producer.is_some() && len as u64 >= self.shared.zero_copy_threshold
348 }
349
350 fn write_into_slot(
356 &mut self,
357 bytes: &[u8],
358 metadata: &Metadata,
359 ) -> Result<Option<OutputPayload>> {
360 let Some((name, generation)) = self
361 .segment
362 .as_ref()
363 .map(|segment| (segment.name.clone(), segment.generation))
364 else {
365 return Ok(None);
366 };
367 let meta_bytes = encode_metadata(metadata)?;
368 let Some(producer) = self.producer.as_mut() else {
369 return Ok(None);
370 };
371 let mut window = match producer.try_allocate(bytes.len()) {
372 Ok(window) => window,
373 Err(_) => {
374 self.shared.count_shm_fallback();
375 return Ok(None);
376 }
377 };
378 let slot = window.slot_index();
379 window.as_mut_slice().copy_from_slice(bytes);
380 match window.commit(&meta_bytes) {
381 Ok(_seq) => Ok(Some(OutputPayload::Shm {
382 segment: name,
383 slot,
384 len: bytes.len() as u64,
385 generation,
386 })),
387 Err(_) => {
388 self.shared.count_shm_fallback();
389 Ok(None)
390 }
391 }
392 }
393
394 fn publish(&self, payload: OutputPayload, metadata: Metadata) -> Result<()> {
396 self.shared.send_request(NodeRequest::SendMessage {
397 output: self.id.clone(),
398 metadata,
399 payload,
400 })
401 }
402
403 fn check_open(&self) -> Result<()> {
405 if self.closed {
406 return Err(NodeError::UnknownOutput {
407 output: self.id.clone(),
408 });
409 }
410 if self.shared.is_closed() {
411 return Err(NodeError::DaemonGone);
412 }
413 Ok(())
414 }
415
416 fn check_size(&self, len: usize) -> Result<()> {
418 let max = self
419 .shared
420 .limits
421 .max_payload_bytes()
422 .min(astrs_data::MAX_PAYLOAD_BYTES);
423 if len > max {
424 return Err(NodeError::PayloadTooLarge { len, max });
425 }
426 Ok(())
427 }
428}
429
430impl Drop for RawOutput {
431 fn drop(&mut self) {
448 let _ = self.close_on_drop();
449 }
450}
451
452pub fn encode_metadata(metadata: &Metadata) -> Result<Vec<u8>> {
458 use astrs_wire::WireEncode;
459 Ok(metadata.encode_to_vec()?)
460}
461
462#[cfg(test)]
463mod tests {
464 #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
465
466 use super::*;
467 use crate::events::{Event, EventSource, QueuedEvent};
468 use crate::payload::Payload;
469 use crate::runtime::NodeRuntime;
470 use crate::session::{OUTGOING_CAPACITY, Outgoing};
471 use astrs_data::array::{Float64Array, IntoArrayRef};
472 use astrs_time::HlcTimestamp;
473 use astrs_wire::{
474 DataflowId, DurationMs, FrameLimits, InputSpec, NodeId, NodeSource, NodeSpawnSpec,
475 OutputSpec, SessionId,
476 };
477 use tokio::sync::mpsc;
478
479 fn session() -> (Arc<SessionShared>, mpsc::Receiver<Outgoing>) {
480 let (sender, receiver) = mpsc::channel(OUTGOING_CAPACITY);
481 let spec = Arc::new(
482 NodeSpawnSpec::new(
483 DataflowId::from_u128(1),
484 NodeId::new("camera").unwrap(),
485 0,
486 NodeSource::Dynamic,
487 )
488 .with_output(OutputSpec::new(DataId::new("image").unwrap())),
489 );
490 let shared = Arc::new(SessionShared::new(
491 spec,
492 SessionId::from_u128(1),
493 sender,
494 Arc::new(EventSource::new()),
495 NodeRuntime::acquire().unwrap(),
496 4096,
497 FrameLimits::uds(),
498 ));
499 (shared, receiver)
500 }
501
502 fn output(shared: &Arc<SessionShared>) -> RawOutput {
503 RawOutput::new(Arc::clone(shared), DataId::new("image").unwrap())
504 }
505
506 fn take_send(receiver: &mut mpsc::Receiver<Outgoing>) -> (Metadata, OutputPayload) {
507 loop {
508 let Ok(Outgoing::Request(request)) = receiver.try_recv() else {
509 panic!("expected a request");
510 };
511 if let NodeRequest::SendMessage {
512 metadata, payload, ..
513 } = *request
514 {
515 return (metadata, payload);
516 }
517 }
518 }
519
520 #[test]
526 fn a_publish_finishes_an_open_deadline_measurement() {
527 let (shared, mut receiver) = session();
528
529 let mut spec = InputSpec::new(
532 DataId::new("frames").unwrap(),
533 PortRef::from_parts("upstream", "frames").unwrap(),
534 );
535 spec.deadline = Some(DurationMs::new(0));
539 shared.source.register_input(&spec).unwrap();
540 shared.source.push_input(
541 &spec.id,
542 QueuedEvent::Input {
543 source: PortRef::from_parts("upstream", "frames").unwrap(),
544 metadata: Metadata::new(HlcTimestamp::new(1, 0)),
545 payload: Payload::inline(vec![9]),
546 },
547 );
548 assert!(
549 shared.source.try_next().unwrap().is_input(),
550 "the input opened a measurement"
551 );
552 assert_eq!(shared.source.stats().deadline_violations, 0, "not yet");
553
554 let mut out = output(&shared);
555 out.send_bytes(vec![1, 2, 3], out.metadata()).unwrap();
556 let _ = take_send(&mut receiver);
557
558 assert_eq!(
559 shared.source.stats().deadline_violations,
560 1,
561 "the publish above must have finished the open measurement"
562 );
563 let event = shared
564 .source
565 .try_next()
566 .expect("the violation reached the control lane");
567 assert!(matches!(event, Event::Error(_)), "{event:?}");
568 }
569
570 #[test]
573 fn a_publish_with_no_open_deadline_is_unaffected() {
574 let (shared, mut receiver) = session();
575 let mut out = output(&shared);
576 out.send_bytes(vec![1, 2, 3], out.metadata()).unwrap();
577 let _ = take_send(&mut receiver);
578 assert_eq!(shared.source.stats().deadline_violations, 0);
579 }
580
581 #[test]
582 fn a_fresh_output_publishes_on_the_daemon_path() {
583 let (shared, mut receiver) = session();
584 let mut out = output(&shared);
585 assert_eq!(out.plane(), RoutePlane::Daemon);
586 assert_eq!(out.id().as_str(), "image");
587 assert!(out.segment().is_none());
588 assert!(out.consumers().is_empty());
589 assert_eq!(out.zero_copy_threshold(), 4096);
590
591 out.send_bytes(vec![1, 2, 3], out.metadata()).unwrap();
592 let (_, payload) = take_send(&mut receiver);
593 assert_eq!(payload.bytes(), Some(&[1, 2, 3][..]));
594 assert_eq!(shared.stats().sends_inline, 1);
595 }
596
597 #[test]
598 fn a_record_batch_is_encoded_before_it_is_sent() {
599 let (shared, mut receiver) = session();
600 let mut out = output(&shared);
601 let batch =
602 RecordBatch::from_payload(Float64Array::from_values([1.0, 2.0]).into_array_ref());
603 out.send_batch(&batch, out.metadata()).unwrap();
604 let (_, payload) = take_send(&mut receiver);
605 let bytes = payload.bytes().unwrap();
606 let decoded = astrs_data::ipc::decode_payload(bytes).unwrap();
607 assert_eq!(decoded, batch);
608 }
609
610 #[test]
611 fn allocate_falls_back_to_the_heap_without_a_producer() {
612 let (shared, mut receiver) = session();
613 let mut out = output(&shared);
614 let mut sample = out.allocate(8).unwrap();
615 assert_eq!(sample.len(), 8);
616 assert!(!sample.is_zero_copy());
617 sample.as_mut_slice().copy_from_slice(&[7; 8]);
618 let metadata = Metadata::new(shared.hlc_now());
619 sample.send(metadata).unwrap();
620
621 let (_, payload) = take_send(&mut receiver);
622 assert_eq!(payload.bytes(), Some(&[7; 8][..]));
623 }
624
625 #[test]
626 fn an_oversized_payload_is_refused_before_it_is_copied() {
627 let (shared, _receiver) = session();
628 let mut out = output(&shared);
629 let max = shared
630 .limits
631 .max_payload_bytes()
632 .min(astrs_data::MAX_PAYLOAD_BYTES);
633 let error = out.check_size(max + 1).unwrap_err();
634 assert!(matches!(error, NodeError::PayloadTooLarge { .. }));
635 assert!(out.allocate(max + 1).is_err());
636 }
637
638 #[test]
639 fn closing_is_idempotent_and_refuses_later_sends() {
640 let (shared, mut receiver) = session();
641 let mut out = output(&shared);
642 out.close().unwrap();
643 out.close().unwrap();
644 assert!(out.is_closed());
645
646 let error = out.send_bytes(vec![1], Metadata::default()).unwrap_err();
647 assert!(matches!(error, NodeError::UnknownOutput { .. }));
648
649 let mut closes = 0;
650 while let Ok(Outgoing::Request(request)) = receiver.try_recv() {
651 if matches!(*request, NodeRequest::OutputDone { .. }) {
652 closes += 1;
653 }
654 }
655 assert_eq!(closes, 1, "one OutputDone, however many close() calls");
656 }
657
658 #[test]
659 fn dropping_an_output_closes_it_as_a_teardown() {
660 let (shared, mut receiver) = session();
666 let id = output(&shared).id.clone();
667 drop(output(&shared));
668 let Ok(Outgoing::Request(request)) = receiver.try_recv() else {
669 panic!("expected a request");
670 };
671 match &*request {
672 NodeRequest::CloseOutputs { outputs } => assert_eq!(outputs, &[id]),
673 other => panic!("expected CloseOutputs, got {other:?}"),
674 }
675 }
676
677 #[test]
678 fn an_explicit_close_stays_an_output_done() {
679 let (shared, mut receiver) = session();
682 let mut out = output(&shared);
683 out.close().unwrap();
684 let Ok(Outgoing::Request(request)) = receiver.try_recv() else {
685 panic!("expected a request");
686 };
687 assert!(matches!(*request, NodeRequest::OutputDone { .. }));
688 }
689
690 #[test]
691 fn a_closed_session_refuses_publishing() {
692 let (shared, _receiver) = session();
693 let mut out = output(&shared);
694 shared.close();
695 assert!(matches!(
696 out.send_bytes(vec![1], Metadata::default()),
697 Err(NodeError::DaemonGone)
698 ));
699 }
700
701 #[test]
702 fn a_route_downgrade_is_picked_up_on_the_next_publish() {
703 let (shared, _receiver) = session();
704 let mut out = output(&shared);
705 shared
706 .routes
707 .slot(&DataId::new("image").unwrap())
708 .offer_downgrade(astrs_wire::RouteDowngradeReason::ConsumerDetached {
709 consumer: PortRef::from_parts("detect", "frames").unwrap(),
710 });
711 out.refresh();
712 assert_eq!(out.plane(), RoutePlane::Daemon);
713 assert!(out.segment().is_none());
714 }
715
716 #[test]
717 fn metadata_is_stamped_with_the_node_clock() {
718 let (shared, _receiver) = session();
719 let out = output(&shared);
720 let first = out.metadata();
721 let second = out.metadata();
722 assert!(second.timestamp >= first.timestamp);
723 assert!(format!("{out:?}").contains("image"));
724 }
725
726 #[test]
727 fn metadata_encodes_for_a_slot() {
728 let metadata = Metadata::default();
729 assert!(!encode_metadata(&metadata).unwrap().is_empty());
730 }
731}