docs/generated/contracts.mdgenerated from code

Reference · 6 min read

slot

Contracts: slot.

Source: crates/lvcs-runtime/src/lib.rs.

ruston main
1/// Takes every output a machine's actions pushed since the last call, and2/// its content check now: `()` for every machine whose context its3/// journaled events determine, and the document's `DocFingerprint`4/// (discussion:owner/32), since a document starts from saves the journal does not5/// hold. The machine keeps its check in its own context and hands it over6/// with its outputs, so nothing else reads the context (discussion:owner/436); the7/// scheduler keeps each step's check as the next one's `before`.8pub type Drain<O, C> = Arc<dyn Fn() -> (Vec<O>, C) + Send + Sync>;910/// What happens to each step once it ran: journaled, then handed to the11/// shell (`journal::to`), only handed on ([`unjournaled`]), or captured12/// for replay ([`capture`]). It is called in step order (an [`Inline`]13/// machine's under its lock), and queues the step's journal entry before14/// it returns; the [`Closing`] it returns awaits the journal writer's15/// acknowledgement and then hands the outputs on (discussion:owner/439). The16/// scheduler awaits it before the machine's next step.17pub type Close<E, O, C = ()> = Arc<dyn Fn(Stepped<E, O, C>) -> Closing + Send + Sync>;1819/// What a [`Close`] leaves to finish once it returned: the journal's20/// acknowledgement, then the outputs handed on.21pub type Closing = Pin<Box<dyn Future<Output = ()> + Send>>;2223/// A [`Closing`] with nothing left to finish.24pub fn closed() -> Closing {25    Box::pin(core::future::ready(()))26}2728/// A machine's step slot (discussion:owner/403): what its scheduler needs to run29/// and journal one step.30pub struct Slot<E, O, C = ()> {31    /// The bounded `actor_kind` value: the journal's and the span's.32    pub kind: ActorKind,33    /// The machine's logger, whose trace each step takes.34    pub trace: Trace,35    /// Takes the outputs each step pushed, and the check after it.36    pub drain: Drain<O, C>,37    /// Where each step goes once it ran.38    pub close: Close<E, O, C>,39    /// The machine's handle on its own queue, which its scheduler fills in40    /// when the machine is built.41    pub myself: Myself<E>,42    /// Set once the machine's task ended, however it ended (it stopped,43    /// a step panicked, or its scope ended).44    pub ended: Ended,45    /// Set by the step that enters the machine's terminal state, before46    /// that step lets go of the machine (discussion:owner/778).47    pub halted: Halted,48    /// Where its scheduler hands every event it took and never stepped,49    /// for the machine's next incarnation (discussion:owner/653); with50    /// none, they are dropped and resolve `false`.51    pub returns: Option<Hand<E>>,52}5354/// Whether a machine has entered its terminal state, which its scheduler55/// sets inside the step that entered it, before the step lets go of the56/// machine (discussion:owner/778). Async code asks this, never `is()`: on a57/// machine stepped on the blocking pool `is()` waits for the step running,58/// parking a Tokio worker that long. Unlike [`Ended`], it says nothing of59/// the events its scheduler hands back, nor of the halting step's journal60/// entry: it is set before that step's close, so it is no durability signal.61#[derive(Debug, Clone)]62pub struct Halted(Arc<tokio::sync::watch::Sender<bool>>);6364impl Default for Halted {65    fn default() -> Self {66        Self::new()67    }68}6970impl Halted {71    /// The flag of a machine that hasn't halted.72    pub fn new() -> Self {73        Self(Arc::new(tokio::sync::watch::Sender::new(false)))74    }7576    /// The machine entered its terminal state.77    fn halt(&self) {78        self.0.send_replace(true);79    }8081    /// Whether the machine entered its terminal state.82    pub fn is(&self) -> bool {83        *self.0.borrow()84    }85}8687/// Whether a machine's task ended, which its scheduler sets once: a88/// machine whose step panicked never reaches its terminal state, so its89/// owner learns it ended here and can start a fresh incarnation.90#[derive(Debug, Clone)]91pub struct Ended(Arc<tokio::sync::watch::Sender<bool>>);9293impl Default for Ended {94    fn default() -> Self {95        Self::new()96    }97}9899impl Ended {100    /// A machine's that hasn't ended.101    pub fn new() -> Self {102        Self(Arc::new(tokio::sync::watch::Sender::new(false)))103    }104105    /// The machine's task ended.106    pub fn end(&self) {107        self.0.send_replace(true);108    }109110    /// Whether the machine's task ended.111    pub fn is(&self) -> bool {112        *self.0.borrow()113    }114115    /// Resolves once the machine's task ended.116    pub fn wait(&self) -> Pin<Box<dyn Future<Output = ()> + Send>> {117        let mut ended = self.0.subscribe();118        Box::pin(async move {119            let _ = ended.wait_for(|ended| *ended).await;120        })121    }122}123124/// A machine's handle on its own queue, for its effect executor: an effect125/// whose answer is the machine's own event (a sleep's `Due`, a refill)126/// sends it back here, and it is queued and journaled like any other127/// (discussion:owner/429). The caller makes it ([`Myself::new`]) before the close128/// that captures it, gives it to the slot ([`Slot::answering`]), and the129/// scheduler fills it in when it builds the machine. Only a machine on its130/// own task ([`TokioScheduler`]) takes events this way; it holds its queue131/// weakly, so a machine nobody else holds still ends.132///133/// **A machine held only by its own `Myself` ends at once; its owner must134/// keep a handle** (the machine itself, or a clone of it) for as long as it135/// should run. `drop(Machine::new(.., myself))` followed by sends through136/// `myself` is a machine that never runs: every send answers `false`, and137/// the scheduler warns that the machine ended before its first event.138pub struct Myself<E> {139    /// The queue's sender, once the machine is built.140    send: Arc<OnceLock<SendSelf<E>>>,141}142143/// Queues one event on a machine's own queue: `false` when the machine144/// ended.145type SendSelf<E> = Arc<dyn Fn(E) -> bool + Send + Sync>;146147impl<E> Default for Myself<E> {148    fn default() -> Self {149        Self::new()150    }151}152153impl<E> Myself<E> {154    /// A handle on a machine not built yet.155    pub fn new() -> Self {156        Self {157            send: Arc::new(OnceLock::new()),158        }159    }160161    /// Queue `event` on the machine's own queue; `false` when it isn't162    /// built, ended, or isn't on its own task.163    pub fn send(&self, event: E) -> bool {164        self.send.get().is_some_and(|send| send(event))165    }166167    /// Point the handle at the machine's queue, as its scheduler does once.168    fn fill(&self, send: SendSelf<E>) {169        if self.send.set(send).is_err() {170            tracing::error!("a machine's own queue was filled in twice; the first stays");171        }172    }173}174175impl<E> Clone for Myself<E> {176    fn clone(&self) -> Self {177        Self {178            send: Arc::clone(&self.send),179        }180    }181}182183impl<E> core::fmt::Debug for Myself<E> {184    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {185        f.debug_struct("Myself")186            .field("built", &self.send.get().is_some())187            .finish()188    }189}190191/// What one event did: the journal entry's parts and the outputs to apply.192#[derive(Debug)]193pub struct Stepped<E, O, C = ()> {194    /// The event, as delivered.195    pub event: E,196    /// Whether the machine's table took it (a guard refusal is not).197    pub accepted: bool,198    /// The logger trace.199    pub trace: Vec<Line>,200    /// The content check before the event.201    pub before: C,202    /// The content check after it ran to completion.203    pub after: C,204    /// The outputs, in push order.205    pub outputs: Vec<O>,206    /// The machine reached sml's terminal `X`: it takes no more events.207    pub stopped: bool,208    /// How long the step ran in the machine.209    pub ran: Duration,210    /// The step's `actor` span, which its close runs in, so every event211    /// its outputs send links back to it (discussion:owner/435).212    pub span: tracing::Span,213}