ingraph 0.1.0

A declaration-driven indexing framework: records and nodes are written as Rust types, and the storage rows, the dataflow between them and the GraphQL query surface are emitted from the declaration.
Documentation
//! WHERE a node's input comes from: the seam the resident parks on, and the select a node with
//! SEVERAL upstreams waits in.
//!
//! # One upstream is an inbox; several are channels and a select
//!
//! A node that draws from ONE upstream has one bounded edge and parks on it — that is
//! [`Inbox`](super::Inbox), and it is what every node in this crate carried until now. A node whose
//! declaration writes a `subscribe(…)` container draws from SEVERAL, and giving those one inbox
//! would couple them: the edge's capacity is shared, so a slow producer filling it stops a fast one
//! from sending at all. So each upstream gets its own edge with its own capacity, and the consumer
//! waits on all of them at once. That is the ruled shape — per-upstream channels and a select — and
//! this module is the runtime half of it.
//!
//! # The seam, and why it is a TYPE PARAMETER rather than an enum
//!
//! [`Intake`] is the dual of [`Sink`](super::Sink) and it is spent the same way: a
//! [`Resident`](super::Resident) carries its intake as a parameter defaulted to the framework's
//! one-upstream shape, so a node with one upstream names nothing and pays nothing, and a node with
//! several hands its own. The intake a `subscribe(…)` container needs is per-node — one field per
//! upstream, each a different message type — which is a struct only that node's own expansion can
//! write; the framework supplies what such a struct is BUILT from: this trait, the [`select`] it
//! parks in, the [`arm`] each upstream contributes, and the [`Pairing`](super::Pairing) that joins the
//! keyed group.
//!
//! # Both engines, one select
//!
//! The async engine awaits [`Intake::park_async`] directly. The thread engine drives that same
//! future on its own thread with [`park_on`], which is [`block_on`](super::lane::block_on) with the
//! sweep as a deadline — so the two engines differ in the same one call they already differed in,
//! and there is one select rather than one per engine.
//!
//! # The select device lives one layer down
//!
//! [`select`], [`Arm`] and [`park_on`] are [`conduit`](crate::conduit)'s, and are re-exported here
//! because this is where the framework spends them. They were promoted when a node's own body
//! became a party that selects: such a body mixes framework edges with channels it opened itself,
//! and a device that only the framework could name would have left it selecting over one of the two.
//! What stays here is what is INBOX-shaped: the seam, its one-source impl, and [`arm`].

use core::{
  future::{Future, pending},
  time::Duration,
};

pub use crate::conduit::{Arm, park_on, select};

use super::{
  ItemId,
  channel::{Inbox, Wake},
};

/// WHERE a node's input comes from — the capability its intake implements.
///
/// Three calls, and they are the three the resident's loop makes: park (each engine's own), and
/// drain, which is what lets one wake serve a whole burst.
///
/// # The futures promise no `Send`
///
/// [`park_async`](Self::park_async) is bounded exactly as
/// [`AsyncOperator::accept`](crate::AsyncOperator::accept) is, and for the same reason: `Send`
/// belongs to the ENGINES. A body that holds a `!Send` intake across an await is an ordinary citizen on the thread
/// engine and is `E0277` at the async door, which is where the question is asked — see
/// [`Ignition::spawn`](crate::Ignition::spawn). [`Sink::deliver`](super::Sink::deliver) does promise
/// it, and the asymmetry is deliberate: a dispatch is awaited from inside a spawned body, while a
/// park is the loop's own wait.
pub trait Intake<In> {
  /// Park until something arrives or `sweep` elapses — the THREAD engine's door.
  ///
  /// `None` is shutdown: every upstream is gone, so nothing can arrive again. A timeout answers
  /// [`Wake::Sweep`], which is the liveness floor rather than an absence.
  fn park(&mut self, sweep: Duration) -> Option<Wake<ItemId, In>>;

  /// Park until something arrives — the ASYNC engine's door.
  ///
  /// No timeout, because there is nothing runtime-neutral to time with; the sweep arrives as
  /// [`Wake::Sweep`] from a [`Sweeper`](super::Sweeper) instead. `None` is shutdown, as above.
  fn park_async(&mut self) -> impl Future<Output = Option<Wake<ItemId, In>>>;

  /// Everything already queued, without waiting, appended to `into`.
  ///
  /// What a woken resident takes before doing anything else, so one wake serves a whole burst. It
  /// appends rather than answering an iterator because a multi-upstream intake has several queues to
  /// walk and a join to run over them, and neither is a borrow of one channel.
  fn drain(&mut self, into: &mut Vec<Wake<ItemId, In>>);
}

/// The ONE-SOURCE intake: a node's own inbox, however many producers send into it.
///
/// The shape every node in this crate carries unless its declaration says otherwise, and the
/// [`Resident`](super::Resident)'s default — so this impl is what makes the seam free for the
/// single-upstream world. Fan-in by [`Outbox`](super::Outbox) clones is unchanged and is a different
/// thing from a keyed group: several producers of ONE message type meeting on one edge, rather than
/// several message types joined into a sum.
impl<T> Intake<T> for Inbox<ItemId, T> {
  #[inline]
  fn park(&mut self, sweep: Duration) -> Option<Wake<ItemId, T>> {
    Self::park(self, sweep)
  }

  #[inline]
  async fn park_async(&mut self) -> Option<Wake<ItemId, T>> {
    Self::park_async(self).await
  }

  #[inline]
  fn drain(&mut self, into: &mut Vec<Wake<ItemId, T>>) {
    into.extend(Self::drain(self));
  }
}

/// ONE arm of a [`select`]: park on `inbox` unless it has already hung up, wrapping what arrives.
///
/// `None` is that upstream's own shutdown — the caller marks the arm closed and selects over what is
/// left. An arm that is already closed NEVER answers, which is what keeps a hung-up upstream from
/// spinning the select: `recv` on a disconnected channel returns immediately, so re-offering one
/// would be a busy loop rather than a wait.
///
/// `wrap` is what tells the arms apart. Each upstream carries a different message type and a select
/// answers ONE, so the arms meet at whatever the intake's own classification wants — usually its
/// per-upstream enum.
///
/// [`conduit::arm`](crate::conduit::arm) is this one at the general transport — same shape, one
/// vocabulary over — and a node's own body selecting over both spends the two side by side.
pub async fn arm<K, T, R>(
  open: bool,
  inbox: &Inbox<K, T>,
  wrap: impl FnOnce(Wake<K, T>) -> R,
) -> Option<R> {
  if !open {
    // Never resolves. The caller has already decided this upstream is finished, and the whole intake
    // answers shutdown when every arm is.
    pending::<()>().await;
  }
  inbox.park_async().await.map(wrap)
}

#[cfg(test)]
mod tests;