Skip to main content

ingraph/drive/
intake.rs

1//! WHERE a node's input comes from: the seam the resident parks on, and the select a node with
2//! SEVERAL upstreams waits in.
3//!
4//! # One upstream is an inbox; several are channels and a select
5//!
6//! A node that draws from ONE upstream has one bounded edge and parks on it — that is
7//! [`Inbox`](super::Inbox), and it is what every node in this crate carried until now. A node whose
8//! declaration writes a `subscribe(…)` container draws from SEVERAL, and giving those one inbox
9//! would couple them: the edge's capacity is shared, so a slow producer filling it stops a fast one
10//! from sending at all. So each upstream gets its own edge with its own capacity, and the consumer
11//! waits on all of them at once. That is the ruled shape — per-upstream channels and a select — and
12//! this module is the runtime half of it.
13//!
14//! # The seam, and why it is a TYPE PARAMETER rather than an enum
15//!
16//! [`Intake`] is the dual of [`Sink`](super::Sink) and it is spent the same way: a
17//! [`Resident`](super::Resident) carries its intake as a parameter defaulted to the framework's
18//! one-upstream shape, so a node with one upstream names nothing and pays nothing, and a node with
19//! several hands its own. The intake a `subscribe(…)` container needs is per-node — one field per
20//! upstream, each a different message type — which is a struct only that node's own expansion can
21//! write; the framework supplies what such a struct is BUILT from: this trait, the [`select`] it
22//! parks in, the [`arm`] each upstream contributes, and the [`Pairing`](super::Pairing) that joins the
23//! keyed group.
24//!
25//! # Both engines, one select
26//!
27//! The async engine awaits [`Intake::park_async`] directly. The thread engine drives that same
28//! future on its own thread with [`park_on`], which is [`block_on`](super::lane::block_on) with the
29//! sweep as a deadline — so the two engines differ in the same one call they already differed in,
30//! and there is one select rather than one per engine.
31//!
32//! # The select device lives one layer down
33//!
34//! [`select`], [`Arm`] and [`park_on`] are [`conduit`](crate::conduit)'s, and are re-exported here
35//! because this is where the framework spends them. They were promoted when a node's own body
36//! became a party that selects: such a body mixes framework edges with channels it opened itself,
37//! and a device that only the framework could name would have left it selecting over one of the two.
38//! What stays here is what is INBOX-shaped: the seam, its one-source impl, and [`arm`].
39
40use core::{
41  future::{Future, pending},
42  time::Duration,
43};
44
45pub use crate::conduit::{Arm, park_on, select};
46
47use super::{
48  ItemId,
49  channel::{Inbox, Wake},
50};
51
52/// WHERE a node's input comes from — the capability its intake implements.
53///
54/// Three calls, and they are the three the resident's loop makes: park (each engine's own), and
55/// drain, which is what lets one wake serve a whole burst.
56///
57/// # The futures promise no `Send`
58///
59/// [`park_async`](Self::park_async) is bounded exactly as
60/// [`AsyncOperator::accept`](crate::AsyncOperator::accept) is, and for the same reason: `Send`
61/// belongs to the ENGINES. A body that holds a `!Send` intake across an await is an ordinary citizen on the thread
62/// engine and is `E0277` at the async door, which is where the question is asked — see
63/// [`Ignition::spawn`](crate::Ignition::spawn). [`Sink::deliver`](super::Sink::deliver) does promise
64/// it, and the asymmetry is deliberate: a dispatch is awaited from inside a spawned body, while a
65/// park is the loop's own wait.
66pub trait Intake<In> {
67  /// Park until something arrives or `sweep` elapses — the THREAD engine's door.
68  ///
69  /// `None` is shutdown: every upstream is gone, so nothing can arrive again. A timeout answers
70  /// [`Wake::Sweep`], which is the liveness floor rather than an absence.
71  fn park(&mut self, sweep: Duration) -> Option<Wake<ItemId, In>>;
72
73  /// Park until something arrives — the ASYNC engine's door.
74  ///
75  /// No timeout, because there is nothing runtime-neutral to time with; the sweep arrives as
76  /// [`Wake::Sweep`] from a [`Sweeper`](super::Sweeper) instead. `None` is shutdown, as above.
77  fn park_async(&mut self) -> impl Future<Output = Option<Wake<ItemId, In>>>;
78
79  /// Everything already queued, without waiting, appended to `into`.
80  ///
81  /// What a woken resident takes before doing anything else, so one wake serves a whole burst. It
82  /// appends rather than answering an iterator because a multi-upstream intake has several queues to
83  /// walk and a join to run over them, and neither is a borrow of one channel.
84  fn drain(&mut self, into: &mut Vec<Wake<ItemId, In>>);
85}
86
87/// The ONE-SOURCE intake: a node's own inbox, however many producers send into it.
88///
89/// The shape every node in this crate carries unless its declaration says otherwise, and the
90/// [`Resident`](super::Resident)'s default — so this impl is what makes the seam free for the
91/// single-upstream world. Fan-in by [`Outbox`](super::Outbox) clones is unchanged and is a different
92/// thing from a keyed group: several producers of ONE message type meeting on one edge, rather than
93/// several message types joined into a sum.
94impl<T> Intake<T> for Inbox<ItemId, T> {
95  #[inline]
96  fn park(&mut self, sweep: Duration) -> Option<Wake<ItemId, T>> {
97    Self::park(self, sweep)
98  }
99
100  #[inline]
101  async fn park_async(&mut self) -> Option<Wake<ItemId, T>> {
102    Self::park_async(self).await
103  }
104
105  #[inline]
106  fn drain(&mut self, into: &mut Vec<Wake<ItemId, T>>) {
107    into.extend(Self::drain(self));
108  }
109}
110
111/// ONE arm of a [`select`]: park on `inbox` unless it has already hung up, wrapping what arrives.
112///
113/// `None` is that upstream's own shutdown — the caller marks the arm closed and selects over what is
114/// left. An arm that is already closed NEVER answers, which is what keeps a hung-up upstream from
115/// spinning the select: `recv` on a disconnected channel returns immediately, so re-offering one
116/// would be a busy loop rather than a wait.
117///
118/// `wrap` is what tells the arms apart. Each upstream carries a different message type and a select
119/// answers ONE, so the arms meet at whatever the intake's own classification wants — usually its
120/// per-upstream enum.
121///
122/// [`conduit::arm`](crate::conduit::arm) is this one at the general transport — same shape, one
123/// vocabulary over — and a node's own body selecting over both spends the two side by side.
124pub async fn arm<K, T, R>(
125  open: bool,
126  inbox: &Inbox<K, T>,
127  wrap: impl FnOnce(Wake<K, T>) -> R,
128) -> Option<R> {
129  if !open {
130    // Never resolves. The caller has already decided this upstream is finished, and the whole intake
131    // answers shutdown when every arm is.
132    pending::<()>().await;
133  }
134  inbox.park_async().await.map(wrap)
135}
136
137#[cfg(test)]
138mod tests;