Skip to main content

astrs_node_api/events/
stream.rs

1//! [`EventStream`] — the node's inbox, in four flavours.
2//!
3//! Blueprint §9.1: *"`EventStream` implements `Iterator` + `Stream` and can
4//! merge external streams. After `Stop` the stream fuses."* All four ways of
5//! reading it — [`recv`](EventStream::recv), [`recv_async`](EventStream::recv_async),
6//! [`Iterator`] and [`Stream`] — are the same queue seen through different
7//! doors, so a node can switch styles without changing its wiring.
8//!
9//! # Which door to use
10//!
11//! | Call | Blocks | Use when |
12//! |---|---|---|
13//! | [`recv`](EventStream::recv) | Yes | An ordinary synchronous node loop |
14//! | [`recv_timeout`](EventStream::recv_timeout) | Yes, bounded | A loop that must do periodic work |
15//! | [`try_recv`](EventStream::try_recv) | No | A node polling its own event loop |
16//! | [`recv_async`](EventStream::recv_async) | No (awaits) | Inside a tokio task |
17//!
18//! The blocking doors return [`NodeError::BlockingInAsync`] rather than
19//! deadlocking when called from a current-thread runtime — see
20//! [`crate::runtime`].
21//!
22//! # A local `Stream`
23//!
24//! This crate defines its own [`Stream`] trait rather than depending on
25//! `futures-core`, which is not on blueprint §18.1's retained list. It is
26//! *signature-identical* to `futures_core::Stream`, so a caller who does have
27//! that crate can write a two-line forwarding adapter — and this crate stays
28//! dependency-clean.
29//!
30//! # Fusing
31//!
32//! [`Event::Stop`] is delivered once and sets the fuse; every later read
33//! returns `None`. [`EventStream::is_fused`] reports it, and
34//! [`EventStream::stop_cause`] remembers why.
35
36use 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
50/// An asynchronous sequence of values.
51///
52/// Signature-identical to `futures_core::Stream`; see the module docs for why
53/// this crate declares its own.
54pub trait Stream {
55    /// The values the stream yields.
56    type Item;
57
58    /// Attempts to pull out the next value, registering the current task for
59    /// wakeup if none is ready.
60    fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>>;
61
62    /// A size hint, in the [`Iterator::size_hint`] shape.
63    fn size_hint(&self) -> (usize, Option<usize>) {
64        (0, None)
65    }
66}
67
68/// The node's event inbox (blueprint §9.1).
69#[derive(Debug)]
70pub struct EventStream {
71    /// The shared inbox the session's reader task pushes into.
72    source: Arc<EventSource>,
73    /// The runtime background work (merged external streams) runs on.
74    runtime: NodeRuntime,
75    /// Set once [`Event::Stop`] has been delivered.
76    fused: bool,
77    /// Why the stream fused.
78    stop_cause: Option<StopCause>,
79    /// Set once a blocking read was refused because this is a current-thread
80    /// runtime. Latched: reporting it once is diagnosis, reporting it every
81    /// call would turn `while let Some(event) = events.recv()` into an
82    /// allocating infinite loop.
83    blocking_refused: bool,
84}
85
86impl EventStream {
87    /// A stream over `source`.
88    #[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    /// The shared inbox, for a caller that wants to feed it directly (the
100    /// testing harness does).
101    #[must_use]
102    pub fn source(&self) -> &Arc<EventSource> {
103        &self.source
104    }
105
106    /// Whether the stream has fused.
107    #[must_use]
108    pub const fn is_fused(&self) -> bool {
109        self.fused
110    }
111
112    /// Why the stream fused, once it has.
113    #[must_use]
114    pub fn stop_cause(&self) -> Option<StopCause> {
115        self.stop_cause.clone()
116    }
117
118    /// A snapshot of the stream's counters.
119    #[must_use]
120    pub fn stats(&self) -> StreamStats {
121        self.source.stats()
122    }
123
124    /// The next event, or `None` if none is ready right now.
125    ///
126    /// Never blocks, and never fuses on emptiness — only on [`Event::Stop`].
127    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    /// Blocks until the next event arrives, the session ends, or the stream
136    /// fuses.
137    ///
138    /// # Panics
139    ///
140    /// Never. A blocking call from a current-thread runtime reports one
141    /// [`Event::Error`] and then ends the stream, rather than deadlocking or
142    /// spinning; use [`EventStream::recv_checked`] to see the typed error
143    /// instead, or [`EventStream::recv_async`] to do the right thing.
144    #[must_use]
145    pub fn recv(&mut self) -> Option<Event> {
146        if self.blocking_refused {
147            // Latched: a loop of `recv()` on a current-thread runtime must
148            // terminate, not report the same misuse forever.
149            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    /// Whether a blocking read was refused because this is a current-thread
161    /// runtime (see [`EventStream::recv`]).
162    #[must_use]
163    pub const fn blocking_refused(&self) -> bool {
164        self.blocking_refused
165    }
166
167    /// [`EventStream::recv`], reporting a misuse instead of swallowing it.
168    ///
169    /// # Errors
170    ///
171    /// [`NodeError::BlockingInAsync`] when called from a current-thread
172    /// runtime's only worker.
173    pub fn recv_checked(&mut self) -> Result<Option<Event>> {
174        self.recv_blocking(None)
175    }
176
177    /// Blocks for at most `timeout`.
178    ///
179    /// Returns `Ok(None)` both when the timeout expires and when the stream
180    /// has ended; [`EventStream::is_fused`] and
181    /// [`EventStream::session_ended`] tell the two apart.
182    ///
183    /// # Errors
184    ///
185    /// As [`EventStream::recv_checked`].
186    pub fn recv_timeout(&mut self, timeout: Duration) -> Result<Option<Event>> {
187        self.recv_blocking(Some(timeout))
188    }
189
190    /// Awaits the next event.
191    ///
192    /// The async twin of [`EventStream::recv`], and the one to use inside a
193    /// tokio task.
194    pub async fn recv_async(&mut self) -> Option<Event> {
195        loop {
196            if self.fused {
197                return None;
198            }
199            // Create the wakeup future *before* checking the queue, so an
200            // event pushed in between cannot be missed.
201            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    /// Awaits the next event, giving up after `timeout`.
215    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    /// Whether the underlying session has ended.
222    #[must_use]
223    pub fn session_ended(&self) -> bool {
224        self.source.is_closed()
225    }
226
227    /// Merges an external event source into this stream.
228    ///
229    /// Everything the receiver yields is delivered on the **control lane**,
230    /// so a user's own timer or sensor thread is never queued behind a
231    /// backlog of frames. The forwarder stops when the sender is dropped or
232    /// the session ends.
233    ///
234    /// # Examples
235    ///
236    /// ```
237    /// # use astrs_node_api::prelude::*;
238    /// # use astrs_node_api::events::EventSource;
239    /// # use astrs_node_api::runtime::NodeRuntime;
240    /// # use std::sync::Arc;
241    /// # fn main() -> Result<(), NodeError> {
242    /// let runtime = NodeRuntime::owned()?;
243    /// let mut events = EventStream::new(Arc::new(EventSource::new()), runtime);
244    /// let sender = events.merge_external_channel(8);
245    /// sender.blocking_send(Event::Error("from my own thread".to_owned())).ok();
246    ///
247    /// let event = events.recv_timeout(std::time::Duration::from_secs(5))?;
248    /// assert!(matches!(event, Some(Event::Error(_))));
249    /// # Ok(())
250    /// # }
251    /// ```
252    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    /// Merges a freshly created channel and hands back its sender.
265    ///
266    /// The convenience form of [`EventStream::merge_external`] for the common
267    /// case where the caller has no channel yet.
268    #[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    /// The blocking read, with an optional deadline.
276    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            // Take the ticket *before* looking, so a push that lands between
283            // the look and the wait is not missed.
284            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                    // Drain whatever landed before the close.
311                    return Ok(self.source.try_next().map(|event| self.observe(event)));
312                }
313            }
314        }
315    }
316
317    /// Records the fuse when a [`Event::Stop`] passes through.
318    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    /// Tells the session the node stopped reading (§7.3
329    /// `EventStreamDropped`), so the daemon can stop queueing for it.
330    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            // The documented `Notify` pattern: build the wakeup future, then
355            // check, then park on it.
356            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                // Woken already: loop round and look again.
369                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        // Control first, so Stop arrives before the queued frames.
449        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        // The lenient face reports it as an event instead of hanging …
509        let event = events.recv().unwrap();
510        assert!(matches!(event, Event::Error(_)));
511        assert!(events.blocking_refused());
512
513        // … exactly once: a `while let Some(event) = events.recv()` loop must
514        // terminate rather than spin on the same misuse.
515        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}