1use core::pin::Pin;
37use core::task::{Context, Poll};
38use std::sync::Arc;
39use std::time::Duration;
40
41use astrs_wire::StopCause;
42use tokio::sync::mpsc::Receiver;
43
44use crate::error::{NodeError, Result};
45use crate::events::Event;
46use crate::events::source::{EventSource, StreamStats};
47use crate::runtime::NodeRuntime;
48use crate::signal::WaitOutcome;
49
50pub trait Stream {
55 type Item;
57
58 fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>>;
61
62 fn size_hint(&self) -> (usize, Option<usize>) {
64 (0, None)
65 }
66}
67
68#[derive(Debug)]
70pub struct EventStream {
71 source: Arc<EventSource>,
73 runtime: NodeRuntime,
75 fused: bool,
77 stop_cause: Option<StopCause>,
79 blocking_refused: bool,
84}
85
86impl EventStream {
87 #[must_use]
89 pub fn new(source: Arc<EventSource>, runtime: NodeRuntime) -> Self {
90 Self {
91 source,
92 runtime,
93 fused: false,
94 stop_cause: None,
95 blocking_refused: false,
96 }
97 }
98
99 #[must_use]
102 pub fn source(&self) -> &Arc<EventSource> {
103 &self.source
104 }
105
106 #[must_use]
108 pub const fn is_fused(&self) -> bool {
109 self.fused
110 }
111
112 #[must_use]
114 pub fn stop_cause(&self) -> Option<StopCause> {
115 self.stop_cause.clone()
116 }
117
118 #[must_use]
120 pub fn stats(&self) -> StreamStats {
121 self.source.stats()
122 }
123
124 pub fn try_recv(&mut self) -> Option<Event> {
128 if self.fused {
129 return None;
130 }
131 let event = self.source.try_next()?;
132 Some(self.observe(event))
133 }
134
135 #[must_use]
145 pub fn recv(&mut self) -> Option<Event> {
146 if self.blocking_refused {
147 return None;
150 }
151 match self.recv_checked() {
152 Ok(event) => event,
153 Err(error) => {
154 self.blocking_refused = true;
155 Some(Event::Error(error.to_string()))
156 }
157 }
158 }
159
160 #[must_use]
163 pub const fn blocking_refused(&self) -> bool {
164 self.blocking_refused
165 }
166
167 pub fn recv_checked(&mut self) -> Result<Option<Event>> {
174 self.recv_blocking(None)
175 }
176
177 pub fn recv_timeout(&mut self, timeout: Duration) -> Result<Option<Event>> {
187 self.recv_blocking(Some(timeout))
188 }
189
190 pub async fn recv_async(&mut self) -> Option<Event> {
195 loop {
196 if self.fused {
197 return None;
198 }
199 let notified = self.source.signal().notified();
202 let ready = self.source.try_next();
203 if let Some(event) = ready {
204 drop(notified);
205 return Some(self.observe(event));
206 }
207 if self.source.is_closed() {
208 return None;
209 }
210 notified.await;
211 }
212 }
213
214 pub async fn recv_async_timeout(&mut self, timeout: Duration) -> Option<Event> {
216 tokio::time::timeout(timeout, self.recv_async())
217 .await
218 .unwrap_or(None)
219 }
220
221 #[must_use]
223 pub fn session_ended(&self) -> bool {
224 self.source.is_closed()
225 }
226
227 pub fn merge_external(&mut self, mut receiver: Receiver<Event>) {
253 let source = Arc::clone(&self.source);
254 let _task = self.runtime.spawn(async move {
255 while let Some(event) = receiver.recv().await {
256 if source.is_closed() {
257 break;
258 }
259 source.push_control(event);
260 }
261 });
262 }
263
264 #[must_use]
269 pub fn merge_external_channel(&mut self, capacity: usize) -> tokio::sync::mpsc::Sender<Event> {
270 let (sender, receiver) = tokio::sync::mpsc::channel(capacity.max(1));
271 self.merge_external(receiver);
272 sender
273 }
274
275 fn recv_blocking(&mut self, timeout: Option<Duration>) -> Result<Option<Event>> {
277 let deadline = timeout.map(|timeout| std::time::Instant::now() + timeout);
278 loop {
279 if self.fused {
280 return Ok(None);
281 }
282 let ticket = self.source.signal().ticket();
285 if let Some(event) = self.source.try_next() {
286 return Ok(Some(self.observe(event)));
287 }
288 if self.source.is_closed() {
289 return Ok(None);
290 }
291 if !self.runtime.can_block() {
292 return Err(NodeError::BlockingInAsync {
293 method: "EventStream::recv",
294 alternative: "EventStream::recv_async",
295 });
296 }
297 let remaining = match deadline {
298 None => None,
299 Some(deadline) => {
300 match deadline.checked_duration_since(std::time::Instant::now()) {
301 Some(remaining) => Some(remaining),
302 None => return Ok(None),
303 }
304 }
305 };
306 match self.source.signal().wait_blocking(ticket, remaining) {
307 WaitOutcome::Signalled => {}
308 WaitOutcome::TimedOut => return Ok(None),
309 WaitOutcome::Closed => {
310 return Ok(self.source.try_next().map(|event| self.observe(event)));
312 }
313 }
314 }
315 }
316
317 fn observe(&mut self, event: Event) -> Event {
319 if let Event::Stop(cause) = &event {
320 self.fused = true;
321 self.stop_cause = Some(cause.clone());
322 }
323 event
324 }
325}
326
327impl Drop for EventStream {
328 fn drop(&mut self) {
331 self.source.abandon();
332 }
333}
334
335impl Iterator for EventStream {
336 type Item = Event;
337
338 fn next(&mut self) -> Option<Self::Item> {
339 self.recv()
340 }
341}
342
343impl core::iter::FusedIterator for EventStream {}
344
345impl Stream for EventStream {
346 type Item = Event;
347
348 fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
349 let this = Pin::into_inner(self);
350 if this.fused {
351 return Poll::Ready(None);
352 }
353 loop {
354 let notified = this.source.signal().notified();
357 let ready = this.source.try_next();
358 if let Some(event) = ready {
359 drop(notified);
360 return Poll::Ready(Some(this.observe(event)));
361 }
362 if this.source.is_closed() {
363 return Poll::Ready(None);
364 }
365 let mut notified = core::pin::pin!(notified);
366 match Future::poll(notified.as_mut(), cx) {
367 Poll::Pending => return Poll::Pending,
368 Poll::Ready(()) => {}
370 }
371 }
372 }
373}
374
375use core::future::Future;
376
377#[cfg(test)]
378mod tests {
379 #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
380
381 use super::*;
382 use crate::events::QueuedEvent;
383 use crate::payload::Payload;
384 use astrs_time::HlcTimestamp;
385 use astrs_wire::{DataId, Metadata, PortRef, PriorityLane, QueuePolicy};
386
387 fn stream() -> (Arc<EventSource>, EventStream) {
388 let source = Arc::new(EventSource::new());
389 source
390 .register_raw(
391 DataId::new("frames").unwrap(),
392 8,
393 QueuePolicy::DropOldest,
394 PriorityLane::Data,
395 )
396 .unwrap();
397 let runtime = NodeRuntime::owned().expect("runtime");
398 let stream = EventStream::new(Arc::clone(&source), runtime);
399 (source, stream)
400 }
401
402 fn message() -> QueuedEvent {
403 QueuedEvent::Input {
404 source: PortRef::from_parts("camera", "image").unwrap(),
405 metadata: Metadata::new(HlcTimestamp::new(1, 0)),
406 payload: Payload::inline(vec![7]),
407 }
408 }
409
410 #[test]
411 fn try_recv_never_blocks() {
412 let (source, mut events) = stream();
413 assert!(events.try_recv().is_none());
414 source.push_input(&DataId::new("frames").unwrap(), message());
415 assert!(events.try_recv().unwrap().is_input());
416 assert!(events.try_recv().is_none());
417 }
418
419 #[test]
420 fn recv_blocks_until_an_event_arrives() {
421 let (source, mut events) = stream();
422 let producer = Arc::clone(&source);
423 let handle = std::thread::spawn(move || {
424 std::thread::sleep(Duration::from_millis(10));
425 producer.push_input(&DataId::new("frames").unwrap(), message());
426 });
427 let event = events.recv().unwrap();
428 assert!(event.is_input());
429 handle.join().unwrap();
430 }
431
432 #[test]
433 fn recv_timeout_returns_none_without_ending_the_stream() {
434 let (_source, mut events) = stream();
435 let event = events.recv_timeout(Duration::from_millis(10)).unwrap();
436 assert!(event.is_none());
437 assert!(!events.is_fused());
438 assert!(!events.session_ended());
439 }
440
441 #[test]
442 fn the_stream_fuses_after_stop() {
443 let (source, mut events) = stream();
444 source.push_input(&DataId::new("frames").unwrap(), message());
445 source.push_control(Event::Stop(StopCause::Requested));
446 source.push_input(&DataId::new("frames").unwrap(), message());
447
448 let first = events.recv().unwrap();
450 assert!(first.is_stop());
451 assert!(events.is_fused());
452 assert_eq!(events.stop_cause(), Some(StopCause::Requested));
453 assert!(events.recv().is_none(), "fused");
454 assert!(events.try_recv().is_none());
455 assert!(events.next().is_none());
456 }
457
458 #[test]
459 fn closing_the_session_ends_the_stream_after_draining() {
460 let (source, mut events) = stream();
461 source.push_input(&DataId::new("frames").unwrap(), message());
462 source.close();
463 assert!(events.recv().unwrap().is_input(), "the tail is drained");
464 assert!(events.recv().is_none());
465 assert!(events.session_ended());
466 }
467
468 #[test]
469 fn the_iterator_face_is_the_same_queue() {
470 let (source, events) = stream();
471 for _ in 0..3 {
472 source.push_input(&DataId::new("frames").unwrap(), message());
473 }
474 source.push_control(Event::Stop(StopCause::Requested));
475 let kinds: Vec<&str> = events.map(|event| event.kind_name()).collect();
476 assert_eq!(kinds, vec!["stop"], "the fuse stops the iteration");
477 }
478
479 #[test]
480 fn dropping_the_stream_marks_the_source_abandoned() {
481 let (source, events) = stream();
482 assert!(!source.is_abandoned());
483 drop(events);
484 assert!(source.is_abandoned());
485 }
486
487 #[test]
488 fn stats_track_delivery() {
489 let (source, mut events) = stream();
490 source.push_input(&DataId::new("frames").unwrap(), message());
491 assert_eq!(events.stats().delivered, 0);
492 let _ = events.try_recv();
493 assert_eq!(events.stats().delivered, 1);
494 assert!(std::ptr::eq(
495 Arc::as_ptr(events.source()),
496 Arc::as_ptr(&source)
497 ));
498 }
499
500 #[tokio::test(flavor = "current_thread")]
501 async fn a_blocking_recv_in_a_current_thread_runtime_is_refused() {
502 let source = Arc::new(EventSource::new());
503 let runtime = NodeRuntime::acquire().unwrap();
504 let mut events = EventStream::new(source, runtime);
505 let error = events.recv_checked().unwrap_err();
506 assert!(matches!(error, NodeError::BlockingInAsync { .. }));
507
508 let event = events.recv().unwrap();
510 assert!(matches!(event, Event::Error(_)));
511 assert!(events.blocking_refused());
512
513 assert!(events.recv().is_none());
516 let mut iterations = 0;
517 while events.next().is_some() {
518 iterations += 1;
519 assert!(iterations < 4, "the loop never terminated");
520 }
521 }
522
523 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
524 async fn recv_async_awaits_an_event() {
525 let source = Arc::new(EventSource::new());
526 source
527 .register_raw(
528 DataId::new("frames").unwrap(),
529 4,
530 QueuePolicy::DropOldest,
531 PriorityLane::Data,
532 )
533 .unwrap();
534 let runtime = NodeRuntime::acquire().unwrap();
535 let mut events = EventStream::new(Arc::clone(&source), runtime);
536
537 let producer = Arc::clone(&source);
538 tokio::spawn(async move {
539 tokio::time::sleep(Duration::from_millis(5)).await;
540 producer.push_input(&DataId::new("frames").unwrap(), message());
541 });
542 let event = events.recv_async().await.unwrap();
543 assert!(event.is_input());
544 }
545
546 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
547 async fn recv_async_timeout_gives_up() {
548 let source = Arc::new(EventSource::new());
549 let runtime = NodeRuntime::acquire().unwrap();
550 let mut events = EventStream::new(source, runtime);
551 assert!(
552 events
553 .recv_async_timeout(Duration::from_millis(10))
554 .await
555 .is_none()
556 );
557 }
558
559 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
560 async fn the_stream_face_polls_the_same_queue() {
561 let source = Arc::new(EventSource::new());
562 let runtime = NodeRuntime::acquire().unwrap();
563 let mut events = EventStream::new(Arc::clone(&source), runtime);
564 source.push_control(Event::AllInputsClosed);
565
566 let polled = core::future::poll_fn(|cx| {
567 let pinned = core::pin::Pin::new(&mut events);
568 Stream::poll_next(pinned, cx)
569 })
570 .await;
571 assert!(matches!(polled, Some(Event::AllInputsClosed)));
572 assert_eq!(Stream::size_hint(&events), (0, None));
573 }
574
575 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
576 async fn external_streams_merge_onto_the_control_lane() {
577 let source = Arc::new(EventSource::new());
578 let runtime = NodeRuntime::acquire().unwrap();
579 let mut events = EventStream::new(source, runtime);
580 let sender = events.merge_external_channel(4);
581 sender
582 .send(Event::Error("external".to_owned()))
583 .await
584 .unwrap();
585 let event = events.recv_async().await.unwrap();
586 let Event::Error(message) = event else {
587 panic!("expected the merged event");
588 };
589 assert_eq!(message, "external");
590 }
591
592 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
593 async fn a_merged_receiver_can_be_supplied_directly() {
594 let source = Arc::new(EventSource::new());
595 let runtime = NodeRuntime::acquire().unwrap();
596 let mut events = EventStream::new(source, runtime);
597 let (sender, receiver) = tokio::sync::mpsc::channel(4);
598 events.merge_external(receiver);
599 sender.send(Event::AllInputsClosed).await.unwrap();
600 assert!(matches!(
601 events.recv_async().await,
602 Some(Event::AllInputsClosed)
603 ));
604 drop(sender);
605 }
606}