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 MIDDLE THIRD, PINNED** — what each face's `process` actually is, asserted at the type and
//! at the moment the work happens.
//!
//! The integration suite drives all four cells and shows what they produce. What it cannot reach is
//! the driver's own middle third, which is private: `process` is where the operator is called, and
//! the ruled property of the blocking cell is a fact about that function's RETURN TYPE rather than
//! about anything it returns.
//!
//! So the first assertion is a coercion — a function item coerces to a `fn` pointer only when the
//! signatures agree, so writing the signature the ruling names and letting the compiler accept it IS
//! the assertion, and any drift makes it `E0308` rather than a passing test. The second is the same
//! claim in the other currency: a future does nothing until it is polled, so *when* the body ran is
//! observable, and the two faces answer differently.
use crate::Context;

use std::sync::{
  Arc,
  atomic::{AtomicUsize, Ordering},
};

use super::{Drained, Pass, Resident, Staged, block_on};

use crate::{
  AsyncOperator, Delivery, Emitter, Item, Operator, Payload, Unpolled,
  drive::{Downstream, Inbox, ItemId, channel},
};

/// A blocking unit that RECORDS when it ran.
struct Counting(Arc<AtomicUsize>);

impl Operator for Counting {
  type Error = core::convert::Infallible;
  type In = u64;
  type Out = u64;

  fn accept(
    &mut self,
    _ctx: &Context,
    delivery: Delivery<Self::In>,
    emitter: &mut Emitter<u64>,
  ) -> Result<(), Self::Error> {
    for item in delivery.into_items() {
      self.0.fetch_add(1, Ordering::SeqCst);
      emitter.emit(item.into_value() * 2);
    }
    Ok(())
  }
}

/// The same, on the awaited face and with a real suspension point in it.
struct AwaitedCounting(Arc<AtomicUsize>);

impl AsyncOperator for AwaitedCounting {
  type Error = core::convert::Infallible;
  type In = u64;
  type Out = u64;

  async fn accept(
    &mut self,
    _ctx: &Context,
    delivery: Delivery<Self::In>,
    emitter: &mut Emitter<u64>,
  ) -> Result<(), Self::Error> {
    for item in delivery.into_items() {
      let value = core::future::ready(item.into_value()).await;
      self.0.fetch_add(1, Ordering::SeqCst);
      emitter.emit(value * 2);
    }
    Ok(())
  }
}

/// The plainest resident there is, on the blocking face.
type Blocking = Resident<Counting, (), (), (), Unpolled, Downstream<u64>, Inbox<ItemId, u64>>;

/// One item, in the shape the driver hands its operator.
fn one(value: u64) -> Delivery<u64> {
  Delivery::in_custody(Payload::One(Item::new(ItemId::new(0), value)))
}

/// **THE ZERO-FUTURE ASSERTION, at the driver.**
///
/// The blocking cell's `process` answers a [`Staged`] and not a future over one. Were it an
/// `async fn` — as it was while there was one face — its return type would be an opaque future and
/// this coercion would be `E0308` naming both. So the thread × blocking path has nothing for
/// `block_on` to drive at the operator's call, which is what *no future minted* means at the one
/// place the operator is actually spent.
#[test]
fn the_blocking_middle_third_answers_a_staged_and_not_a_future() {
  let process: fn(&mut Blocking, Delivery<u64>, &mut Drained) -> Staged<u64> = Blocking::process;
  assert_eq!(
    core::mem::size_of_val(&process),
    core::mem::size_of::<fn()>(),
    "a function pointer, which is what the coercion produced"
  );
}

/// The same claim in the currency a future is spent in: the blocking middle third has ALREADY DONE
/// the work when it answers.
#[test]
fn the_blocking_middle_third_has_run_by_the_time_it_answers() {
  let counted = Arc::new(AtomicUsize::new(0));
  let (_feed, inbox) = channel::<ItemId, u64>(1);
  let mut resident = Resident::new("count", Counting(Arc::clone(&counted)), inbox);
  let mut report = Drained::default();

  let staged = resident.process(one(21), &mut report);
  assert_eq!(
    counted.load(Ordering::SeqCst),
    1,
    "the body ran during the call"
  );
  assert_eq!(staged.outputs, [42]);
}

/// And the awaited one has NOT, which is what makes the pair a distinction rather than a
/// description of both: its answer is a future, and a future does nothing until it is polled.
#[test]
fn the_awaited_middle_third_has_not_run_until_it_is_driven() {
  let counted = Arc::new(AtomicUsize::new(0));
  let (_feed, inbox) = channel::<ItemId, u64>(1);
  let mut resident = Resident::new("count", AwaitedCounting(Arc::clone(&counted)), inbox);
  let mut report = Drained::default();

  let pending = resident.process(one(21), &mut report);
  assert_eq!(
    counted.load(Ordering::SeqCst),
    0,
    "nothing has run: the call answered a future"
  );
  let staged: Staged<u64> = block_on(pending);
  assert_eq!(counted.load(Ordering::SeqCst), 1, "and this is what ran it");
  assert_eq!(staged.outputs, [42]);
}

/// The per-item bookkeeping either side of the call is ONE body, and this is what says so: a pass
/// folded by hand answers the same [`Staged`] the two middles build, so a face that drifted in
/// anything but its call would show up here.
#[test]
fn a_pass_absorbs_an_item_the_same_way_for_either_face() {
  let mut pass: Pass<u64> = Pass::opening(1);
  let mut emitter = Emitter::new();
  emitter.emit(42);
  pass.absorb(
    ItemId::new(7),
    emitter,
    Ok::<(), core::convert::Infallible>(()),
  );

  assert_eq!(pass.outputs, [42], "the emission was staged");
  assert_eq!(pass.owner, [0], "attributed to the input that produced it");
  assert_eq!(pass.verdict.tally.processed, 1);
  assert_eq!(pass.verdict.tally.failed, 0);
}