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
//! The channel intake: a data edge opened at its declared options, and the one vocabulary both engines
//! wake on.

use super::{
  Rings,
  message::Delivery,
  poll::{PollUpstream, Ticked, Ticker},
};

mod spec;

pub use spec::ChannelOptions;

/// What woke a resident.
///
/// It is the INBOX's message type rather than a value the loop computes, and that is what makes the
/// two engines one loop. A thread self-times, so its sweep is a `recv_timeout` expiry turned into
/// this variant; an async task is rung by a [`Sweeper`](super::Sweeper), so its sweep arrives as
/// this variant on the wire. Either way the loop body reads one enum, and shutdown is neither
/// variant — it is the receive failing because every sender is gone.
#[derive(Debug)]
pub enum Wake<K, T> {
  /// Real data, and the oneshot it is owed an answer on.
  Delivered(Delivery<T, K>),
  /// Look again. Carries nothing, is safe to lose, and coalesces into one already queued — which is
  /// why a full channel drops it instead of blocking the ringer.
  Sweep,
  /// One declared POLL UPSTREAM came due — look at THAT store again.
  ///
  /// It is [`Sweep`](Self::Sweep) with an identity, and the identity is the whole difference: a
  /// sweep is the liveness floor under every node, and a tick is a schedule one upstream declared. It
  /// is safe to lose for the same reason a sweep is, and coalesces in a cell of its own rather than
  /// on this channel — see [`Ticked`].
  Tick(Ticked),
}

/// The sending half of a bounded data edge.
///
/// BOUNDED and BLOCKING is the whole posture: [`deliver`](Self::deliver) waits for room rather than
/// dropping, so a slow consumer becomes backpressure on its producer and nothing on this edge is
/// ever lost. That is the opposite of the sweep's posture on the same channel, and deliberately: a
/// wake carries no information and data carries all of it.
#[derive(Debug)]
pub struct Outbox<K, T> {
  tx: flume::Sender<Wake<K, T>>,
}

impl<K, T> Outbox<K, T> {
  /// Hand `delivery` to the consumer, WAITING for room.
  ///
  /// `Err` gives the delivery back, and the caller's honest answer to that is a
  /// [`ServiceInactive`](crate::SkipReason::ServiceInactive) skip: the consumer is gone, so nothing
  /// downstream will ever release these items and holding them would stall the sender forever.
  #[inline]
  pub fn deliver(&self, delivery: Delivery<T, K>) -> Result<(), Delivery<T, K>> {
    self
      .tx
      .send(Wake::Delivered(delivery))
      .map_err(|e| match e.0 {
        Wake::Delivered(delivery) => delivery,
        // Unreachable by construction: this call site is the only one that builds the message, and it
        // builds `Delivered`. `expect` rather than a silent fallback, because a future variant added
        // to `Wake` must not be able to make this arm return the wrong delivery.
        Wake::Sweep | Wake::Tick(_) => {
          unreachable!("`deliver` sends `Delivered` and flume returns what it took")
        }
      })
  }

  /// [`deliver`](Self::deliver) for the async engine — the same blocking-for-room semantics
  /// expressed as backpressure a task can await.
  #[inline]
  pub async fn deliver_async(&self, delivery: Delivery<T, K>) -> Result<(), Delivery<T, K>> {
    self
      .tx
      .send_async(Wake::Delivered(delivery))
      .await
      .map_err(|e| match e.0 {
        Wake::Delivered(delivery) => delivery,
        Wake::Sweep | Wake::Tick(_) => unreachable!("`deliver_async` sends `Delivered`"),
      })
  }

  /// Hand `delivery` over WITHOUT waiting.
  ///
  /// `Err` gives the delivery back for either of the two reasons a send can fail at once — no room,
  /// or nobody there — and [`is_disconnected`](Self::is_disconnected) is what tells them apart.
  /// They are one arm here because the caller that wants the distinction is the one that has to
  /// DECIDE about it, and that caller is the overflow gate:
  /// [`Sheds::deliver`](crate::Sheds::deliver) asks the policy about the first and hands the
  /// delivery straight back on the second.
  ///
  /// [`deliver`](Self::deliver) is still the plain door and still the one nearly everything takes:
  /// bounded and blocking is the shipped posture, and this is what a deployment that ruled
  /// otherwise reaches through.
  #[inline]
  pub fn try_deliver(&self, delivery: Delivery<T, K>) -> Result<(), Delivery<T, K>> {
    self
      .tx
      .try_send(Wake::Delivered(delivery))
      .map_err(|error| match error.into_inner() {
        Wake::Delivered(delivery) => delivery,
        // Unreachable by construction, as [`deliver`](Self::deliver)'s own arm is.
        Wake::Sweep | Wake::Tick(_) => {
          unreachable!("`try_deliver` sends `Delivered` and flume returns what it took")
        }
      })
  }

  /// How many messages are queued on this edge.
  ///
  /// DELIVERIES, as a channel's depth is counted everywhere in this layer — a batch is one.
  #[inline]
  #[must_use]
  pub fn len(&self) -> usize {
    self.tx.len()
  }

  /// Whether none is.
  #[inline]
  #[must_use]
  pub fn is_empty(&self) -> bool {
    self.tx.is_empty()
  }

  /// What bounds this edge, or `None` where nothing does — the pair
  /// [`Occupancy`](crate::Occupancy) is built from.
  #[inline]
  #[must_use]
  pub fn capacity(&self) -> Option<usize> {
    self.tx.capacity()
  }

  /// Whether the consumer has hung up.
  #[inline]
  #[must_use]
  pub fn is_disconnected(&self) -> bool {
    self.tx.is_disconnected()
  }

  /// This edge's sending half AS A SINK, consuming the outbox — what a BRIDGED
  /// [`Feed`](crate::Feed) is built over.
  ///
  /// By value rather than by reference, and that is the bridge's teardown ordering rather than a
  /// convenience: the whole point of handing an origin the edge itself is that the edge closes when
  /// the origin's life ends, and a clone left behind here would keep the consumer's inbox open past
  /// it. See [`Feed::bridging`](crate::Feed::bridging).
  #[inline]
  pub(crate) fn into_sink(self) -> flume::r#async::SendSink<'static, Wake<K, T>> {
    self.tx.into_sink()
  }

  /// A sweep ringer for this edge's consumer.
  ///
  /// It is minted from the SENDING half because that is the half flume lets one clone; a receiver
  /// cannot manufacture a sender. Handing it to a [`Sweeper`](super::Sweeper) is what gives an
  /// async resident its clock.
  #[inline]
  #[must_use]
  pub fn nudge(&self) -> Nudge<K, T> {
    Nudge {
      tx: self.tx.clone(),
    }
  }

  /// A POLL ringer for this edge's consumer, speaking for `upstream`.
  ///
  /// [`nudge`](Self::nudge)'s sibling, minted from the sending half for the same reason and
  /// carrying one thing more: a tick names WHICH of the consumer's declared poll upstreams came due,
  /// so a node reaping one store and compacting another is told which of them to look at.
  ///
  /// Handing these to a [`Sweeper`](super::Sweeper) — as [`Schedule::cadences`](super::Schedule) —
  /// is what gives an async poll node its clock; a THREAD node needs none of them, because it times
  /// its own upstreams.
  #[inline]
  #[must_use]
  pub fn ticker(&self, upstream: PollUpstream) -> Ticker<K, T> {
    Ticker::new(upstream, self.tx.clone())
  }
}

// Hand-written so `K`/`T` need not be `Clone`: a sender is a handle, and cloning one is what
// fan-in IS — several producers holding the same consumer's inbox.
impl<K, T> Clone for Outbox<K, T> {
  #[inline]
  fn clone(&self) -> Self {
    Self {
      tx: self.tx.clone(),
    }
  }
}

/// The sweep half of an inbox: rings, never blocks, never carries data.
///
/// It holds a full sender, so it also keeps the channel alive — which is why a
/// [`Sweeper`](super::Sweeper) must be dropped before a shutdown-by-disconnect can complete, and
/// why [`Sweeper`](super::Sweeper) drops its ringers when the clock stops.
#[derive(Debug)]
pub struct Nudge<K, T> {
  tx: flume::Sender<Wake<K, T>>,
}

impl<K, T> Clone for Nudge<K, T> {
  #[inline]
  fn clone(&self) -> Self {
    Self {
      tx: self.tx.clone(),
    }
  }
}

impl<K, T> Rings for Nudge<K, T>
where
  K: Send,
  T: Send,
{
  #[inline]
  fn ring(&self) -> bool {
    match self.tx.try_send(Wake::Sweep) {
      // A full channel means the consumer already has work queued, so the wake it would have
      // carried is redundant — coalesced, not lost.
      Ok(()) | Err(flume::TrySendError::Full(_)) => true,
      Err(flume::TrySendError::Disconnected(_)) => false,
    }
  }
}

/// The receiving half — a node's inbox.
///
/// One inbox per node, however many producers: fan-in is several [`Outbox`] clones, and a
/// [`ChangeIntake`](super::ChangeIntake) is one more producer among them. That is what makes the
/// two delivery modes mixable without the loop knowing which mode a delivery came from.
#[derive(Debug)]
pub struct Inbox<K, T> {
  rx: flume::Receiver<Wake<K, T>>,
}

impl<K, T> Inbox<K, T> {
  /// Park until something arrives or `sweep` elapses — the THREAD engine's door.
  ///
  /// `None` is shutdown: every sender is gone, so nothing can arrive again.
  #[inline]
  pub fn park(&self, sweep: core::time::Duration) -> Option<Wake<K, T>> {
    match self.rx.recv_timeout(sweep) {
      Ok(wake) => Some(wake),
      Err(flume::RecvTimeoutError::Timeout) => Some(Wake::Sweep),
      Err(flume::RecvTimeoutError::Disconnected) => None,
    }
  }

  /// 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.
  #[inline]
  pub async fn park_async(&self) -> Option<Wake<K, T>> {
    self.rx.recv_async().await.ok()
  }

  /// Everything already queued, without waiting — what a woken resident drains before doing
  /// anything else, so one wake serves a whole burst.
  ///
  /// `impl Iterator` and not the transport's own drain type: which channel crate carries this layer
  /// is an implementation choice, and a signature naming it would make the choice part of the API.
  #[inline]
  pub fn drain(&self) -> impl Iterator<Item = Wake<K, T>> {
    self.rx.drain()
  }

  /// How many messages are queued.
  #[inline]
  #[must_use]
  pub fn len(&self) -> usize {
    self.rx.len()
  }

  /// Whether none is.
  #[inline]
  #[must_use]
  pub fn is_empty(&self) -> bool {
    self.rx.is_empty()
  }

  /// Whether every sender is gone.
  #[inline]
  #[must_use]
  pub fn is_disconnected(&self) -> bool {
    self.rx.is_disconnected()
  }

  /// THE EVICTION HAND onto this edge — what an [`OverflowPolicy`](crate::OverflowPolicy) answering
  /// [`DropOldest`](crate::OverflowDecision::DropOldest) needs and what nothing else does.
  ///
  /// A sender cannot make room in a queue it can only push onto, so the party that takes the oldest
  /// message back out has to hold a RECEIVING half — which is what this is.
  ///
  /// # It KEEPS THE EDGE OPEN
  ///
  /// An evictor is a receiver, so an edge with one outstanding is an edge whose senders never see a
  /// disconnect. That is the same fact a [`Sweeper`](super::Sweeper)'s ringers carry from the other
  /// side, and it has the same consequence: an evictor belongs to the thing it serves and is
  /// dropped with it, or the shutdown wave stops at this node.
  #[inline]
  #[must_use]
  pub fn evictor(&self) -> Evictor<K, T> {
    Evictor {
      rx: self.rx.clone(),
    }
  }
}

/// THE EVICTION HAND: takes the OLDEST message out of an edge so a newer one can take its place.
///
/// Minted by [`Inbox::evictor`], which is where the sentence about keeping the edge open is
/// written.
#[derive(Debug)]
pub struct Evictor<K, T> {
  rx: flume::Receiver<Wake<K, T>>,
}

impl<K, T> Evictor<K, T> {
  /// Take the oldest DELIVERY out, or `None` where there is none to take.
  ///
  /// Wakes and ticks queued ahead of it are discarded on the way, which loses nothing: both are
  /// *look again* messages, both are safe to lose by their own contract, and both coalesce into the
  /// look the consumer is about to do anyway. A delivery is the only thing on this edge whose loss
  /// is worth an obituary, so it is the only thing this hands back.
  #[inline]
  #[must_use]
  pub fn evict(&self) -> Option<Delivery<T, K>> {
    while let Ok(wake) = self.rx.try_recv() {
      if let Wake::Delivered(delivery) = wake {
        return Some(delivery);
      }
    }
    None
  }

  /// How many messages are queued on the edge it evicts from.
  #[inline]
  #[must_use]
  pub fn len(&self) -> usize {
    self.rx.len()
  }

  /// Whether none is.
  #[inline]
  #[must_use]
  pub fn is_empty(&self) -> bool {
    self.rx.is_empty()
  }
}

// Hand-written so `K`/`T` need not be `Clone`, as [`Outbox`]'s own is.
impl<K, T> Clone for Evictor<K, T> {
  #[inline]
  fn clone(&self) -> Self {
    Self {
      rx: self.rx.clone(),
    }
  }
}

/// A bounded data edge of `capacity` messages.
///
/// The capacity is the memory bound between two nodes, and it is a count of DELIVERIES rather than
/// of items — a batch is one message — so a pipeline's real bound is `capacity × batch`. Zero is
/// legal and means a rendezvous: the sender waits until the consumer takes it.
///
/// The DEPTH-ONLY spelling, which is what a hand-wired arrangement writes. What a deployment's
/// resolved word opens is [`open`].
#[inline]
#[must_use]
pub fn channel<K, T>(capacity: usize) -> (Outbox<K, T>, Inbox<K, T>) {
  let (tx, rx) = flume::bounded(capacity);
  (Outbox { tx }, Inbox { rx })
}

/// A data edge opened at `spec` — the door a RESOLVED declaration comes through.
///
/// The kind is a value here rather than a call site, which is the whole of what makes the channel
/// word configurable: the wiring walk asks the validate walk what this edge resolved to and opens
/// it, so an author's default and a deployment's override reach the same one call.
///
/// An unbounded edge keeps every other property of a bounded one — the same [`Wake`] vocabulary, the
/// same nudge and tick posture, nothing dropped. What it gives up is backpressure, and the
/// declaration that asked for it is where that trade is written down.
#[inline]
#[must_use]
pub fn open<K, T>(spec: ChannelOptions) -> (Outbox<K, T>, Inbox<K, T>) {
  match spec {
    ChannelOptions::Bounded(capacity) => channel(capacity),
    ChannelOptions::Unbounded => {
      let (tx, rx) = flume::unbounded();
      (Outbox { tx }, Inbox { rx })
    }
  }
}

#[cfg(test)]
mod tests;