docs/generated/contracts.mdgenerated from code
Reference · 6 min read
slot
Contracts: slot.
Read as
Source: crates/lvcs-runtime/src/lib.rs.
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}