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 STAGING LEDGER**: what a launch has already BUILT and still holds, and the goodbyes it says
//! when the walk refuses BEFORE anything ignited.
//!
//! [`Ignition::unwind`](super::Ignition::unwind) is the failed launch's duty for the values that
//! RAN. This is the same duty one moment earlier, and the difference between the two is not the
//! chain — it is one and the same — but WHERE THE VALUE IS.
//!
//! | when it fails | where the values are | how the chain reaches them |
//! |---|---|---|
//! | after ignition | on an engine | the party's own settlement seat, [`Settlement`](super::Wiring) |
//! | BEFORE ignition | in the launch walk's own hands | directly — this ledger, consumed |
//!
//! Post-ignition a running loop must be told, and the goodbye has to travel back from wherever the
//! value went. Pre-ignition NOTHING RUNS: ownership never left the walk, so there is no transport to
//! build. The values are consumed where they stand — a wired-but-unignited party through
//! [`Resident::into_operator`](crate::Resident::into_operator), a bare constructed value straight —
//! and what is written down is exactly what the shutdown's chain already understands: a
//! [`Farewell`] per enrolment, in enrolment order.
//!
//! # The ORDER is the launch's own, and it is written forwards
//!
//! Entries are staged as they are built and the chain says them BACKWARDS —
//! [`farewell`](super::teardown::farewell) is the one walk, so this ledger is in the order things
//! happened and nothing here reverses anything. The RESOURCES are not in it at all: they are the
//! [`Resources`](super::Resources)'s, released after this ledger is spent, which is the resources-last
//! rule read from the only place that can keep it.
//!
//! # Why the unwind that spends it is SYNCHRONOUS
//!
//! A goodbye is a [`Goodbye`](super::Goodbye) — a future that promises no `Send`, on purpose, so
//! that a value pinned to one thread can say one. An `async fn` unwind would hold that future across
//! its own await points and make the WHOLE emitted launch `!Send` for any deployment with one such
//! node. So [`Creation::unwind`](super::Creation::unwind) and
//! [`Wiring::unwind`](super::Wiring::unwind) are ordinary functions that drive the chain to its end
//! inside themselves, exactly as [`Ignition::unwind`](super::Ignition::unwind) does, and a launch
//! future stays as mobile as it was.
//!
//! # A value that enrolled nothing costs nothing to stage
//!
//! [`declared`](Staging::declared) reads [`Declared::TEARDOWN`](super::Declared::TEARDOWN) and drops
//! the value where it is `false`. No row, no allocation, no name in anybody's report — the same
//! economy the ignition keeps for a node that never wrote the word, spelled at the other end of the
//! launch.

use super::{
  AsyncTeardown, Declared,
  teardown::{Farewell, Parting},
};

#[cfg(test)]
mod tests;

/// The values a launch walk has BUILT and not yet handed on — the pre-ignition unwind's own list.
///
/// Filled by the party that holds the values, which is the launch walk itself: an emitted
/// `<Root>::launch` stages the node bag's remaining slots and each wired-but-unignited resident, and
/// a hand-written launch stages whatever it is holding. Spent by
/// [`Creation::unwind`](super::Creation::unwind) or [`Wiring::unwind`](super::Wiring::unwind),
/// whichever walk was the one that refused.
///
/// # Examples
///
/// ```
/// use ingraph::Staging;
/// # use ingraph::{Block, Buffered, Declared, Effect, Goodbye, Unchanneled};
///
/// struct Camera {
///   handle: u32,
/// }
///
/// # impl Declared for Camera {
/// #   const EFFECT: Effect = Effect::Pure;
/// #   const TEARDOWN: bool = true;
/// #   type Channels = Unchanneled;
/// #   type Mode = Block;
/// #   type Options = ();
/// #   type Pair = Buffered;
/// #   type Wires<O> = ingraph::Downstream<O>;
/// #   type Attribution<O> = ();
/// #   fn goodbye(self) -> Goodbye {
/// #     Box::pin(async move { let _ = self.handle; Ok(()) })
/// #   }
/// # }
/// struct Counter;
/// # impl Declared for Counter {
/// #   const EFFECT: Effect = Effect::Pure;
/// #   type Channels = Unchanneled;
/// #   type Mode = Block;
/// #   type Options = ();
/// #   type Pair = Buffered;
/// #   type Wires<O> = ingraph::Downstream<O>;
/// #   type Attribution<O> = ();
/// # }
///
/// let mut staged = Staging::new();
/// staged.declared::<Camera>("camera", Camera { handle: 7 });
/// // A declaration that wrote no `teardown` word is dropped as it is staged.
/// staged.declared::<Counter>("counter", Counter);
///
/// assert_eq!(staged.len(), 1);
/// ```
#[derive(Debug, Default)]
pub struct Staging {
  farewells: Vec<Farewell>,
}

impl Staging {
  /// Nothing built yet.
  #[inline]
  #[must_use]
  pub const fn new() -> Self {
    Self {
      farewells: Vec::new(),
    }
  }

  /// Stage a DECLARED node's value under `name` — the `teardown` word's road on this side.
  ///
  /// The branch is [`Declared::TEARDOWN`](super::Declared::TEARDOWN) and the goodbye it reaches is
  /// [`Declared::goodbye`](super::Declared::goodbye), which is the very pair the ignition reads one
  /// stage on. So a launch walk stages every mount it holds with one line each and never names
  /// [`AsyncTeardown`], and a declaration that enrolled nothing is dropped right here.
  ///
  /// What a caller stages is the OPERATOR. A party that was wired and never ignited is
  /// [`Resident::into_operator`](crate::Resident::into_operator) first — the drive layer's own
  /// wrapping goes before the goodbye, so the value's last act is said to a node nothing can still
  /// reach.
  pub fn declared<N>(&mut self, name: &str, value: N) -> &mut Self
  where
    N: Declared + Send + 'static,
  {
    if !N::TEARDOWN {
      drop(value);
      return self;
    }
    self.stage(name, move || Parting::Say(N::goodbye(value)))
  }

  /// Stage anything else the walk holds under `name` — the [`AsyncTeardown`] door, for a value that
  /// belongs to no declaration.
  ///
  /// [`Ignition::teardown`](super::Ignition::teardown)'s twin one stage earlier, and the same
  /// posture: it is what a hand-written launch enrols a file handle or a lock it opened itself
  /// through, and nothing calls it for a node.
  pub fn teardown<T>(&mut self, name: &str, value: T) -> &mut Self
  where
    T: AsyncTeardown + Send + 'static,
  {
    self.farewells.push(Farewell::new(name.to_owned(), value));
    self
  }

  /// How many staged values have a goodbye to say.
  #[inline]
  #[must_use]
  pub fn len(&self) -> usize {
    self.farewells.len()
  }

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

  /// Push one enrolment, whatever door minted it.
  fn stage<F>(&mut self, name: &str, say: F) -> &mut Self
  where
    F: FnOnce() -> Parting + Send + 'static,
  {
    self.farewells.push(Farewell::held(name.to_owned(), say));
    self
  }

  /// The chain, in ENROLMENT order — what the walk that refused hands to
  /// [`farewell`](super::teardown::farewell).
  pub(super) fn into_farewells(self) -> Vec<Farewell> {
    self.farewells
  }
}