//! The chain lifecycle: chain start, and the two chain-end paths - a //! chain's finish (the frame's teardown boundary, the chain-end rules for //! the tasks it owns, and the outcome's delivery to the root, a call //! parent, or a task entry) and the abort of a chain with everything it //! transitively blocks on or owns. use std::num::NonZeroUsize; use std::sync::{Arc, Mutex}; use runvil_types::error::{ErrorCode, place}; use runvil_types::ids::{AbandonReason, ChainId, TaskId}; use runvil_vfs::Access; use crate::execute::context::ChainState; use crate::execute::run::EffectId; use crate::execute::section_context::TaskSeed; use crate::lua::Answer; use crate::model::ModelBinding; use crate::section_pos::SectionPos; use crate::{Result, error}; use super::chain_record::{CallDepth, ChainKind, Walk}; use super::{Chain, ChainIndex, ChatAnchor, Counters, GENERIC_COMPLETION, Scheduler}; /// What one chain's step left the run with: the run goes on, or the step /// decided the run's result. #[derive(Debug)] pub(super) enum ChainStep { /// The run goes on. Continue, /// The run ended with this result: the root's outcome, or a failure /// fatal to the whole run. RunEnded(Result), } impl Chain { /// Returns the chain's current model: the binding `models.use` last /// stored, else the model the chain started on. `None` means the caller /// supplied no model. /// /// # Errors /// Returns an `Internal` failure when the selection's lock is poisoned. pub(super) fn current_model(&self) -> Result> { self.selection .lock() .map(|selection| selection.clone()) .map_err(|_| error::make_internal_error("model selection lock was poisoned")) } } /// Everything a new chain starts from. pub(super) struct ChainStart { /// The chain's hierarchical id. pub(super) lineage: ChainId, /// The id counters the chain starts from: zero for every chain. pub(super) counters: Counters, /// The chain's fork of the run state. pub(super) ctx: ChainState, /// The model the chain's current model starts on: the `default` binding /// of its prompt for the root walk and for the chain an `execute` /// starts, and a copy of the parent's current model, taken when the /// call or spawn was dispatched, for a `call` child or a task. pub(super) model: Option, /// The chain's VFS access capability: the root identity for the root /// walk, the caller's for a `call` child and for the chain an /// `execute` starts, a fork of the spawner's for a task. pub(super) access: Arc, /// The section the chain starts at, which its walk continues from: /// the first top-level section of its prompt for the root walk and /// for the chain an `execute` starts. pub(super) start: SectionPos, /// What kind of chain it is. pub(super) kind: ChainKind, /// The `var` the chain's first section seeds from: a call or task /// chain's caller snapshot, discarded with the chain, and an empty /// table for the root walk and for the chain an `execute` starts. pub(super) var: serde_json::Value, /// The chain's call nesting depth. pub(super) call_depth: CallDepth, /// The chain's effective admission limit for the tasks it spawns: /// the caller's own for a call child or a task, the run's ceiling for /// the root. pub(super) concurrency: NonZeroUsize, } impl Scheduler { /// Creates one chain from `start` and returns its arena index. A /// fresh chain enters its first section on its first step, taking /// entry 0 of its own id. Until its first entry the chain reports under /// the section at its start, or the prompt's name when the start is /// past its slice. The chain's task is its own id for a task /// chain, its call parent's for a `call` child, and task `0` for the /// root walk. /// /// # Errors /// Returns an `Internal` failure when the run's chain count exceeds `u32`. pub(super) fn start_chain(&mut self, start: ChainStart) -> Result { let task = match &start.kind { ChainKind::Root => TaskId::from(ChainId::root()), ChainKind::Call { parent } => self.chains[*parent].task.clone(), ChainKind::Task => TaskId::from(start.lineage.clone()), }; let entered_name = start.start.name(start.ctx.prompt()).to_owned(); self.chains.push(Chain { lineage: start.lineage, counters: start.counters, kind: start.kind, task, seed: TaskSeed::default(), parked: None, ctx: start.ctx, selection: Arc::new(Mutex::new(start.model)), access: Some(start.access), entered: None, walk: Walk::new(start.start), entered_name, var: start.var, call_depth: start.call_depth, concurrency: start.concurrency, anchor: ChatAnchor::default(), }) } /// Finishes one chain: the frame's teardown boundary when the chain /// ends mid-section, the chain-end rules for the tasks it owns (a live /// task makes the outcome `make_tasks_live_error` and is abandoned), then the /// chain-end joins - every owned task's final clock merges into this /// chain's own, so a waiting owner sees the whole subtree /// transitively - and finally the outcome's delivery: the run's result /// for the root chain, the call answer for a child chain, the task /// entry's outcome for a spawned chain. /// /// Delivery is one of those three ways and a `Determinism` outcome /// takes none of them: it ends the run before the delivery match. A /// chain that ended with no text delivers by its kind: the run's result /// is the shared generic completion, a task's is the empty string, and /// a `call` child's answer holds no text, so the call returns nil. /// /// `outcome` is the chain's end: the text a `return` gave, `None` for /// a `return` that gave nil or no value and for a walk that ran off its /// slice's last section, or the chain's failure. pub(super) fn finish(&mut self, id: ChainIndex, outcome: Result>) -> ChainStep { let prompt = self.prompt_of(id); let chain = &mut self.chains[id]; let blocks = chain.blocks(&prompt); let parent = chain.kind.parent(); let is_task = matches!(chain.kind, ChainKind::Task); // `None` when the chain ended by exhausting its slice: the last // section's frame already dropped at the fall-through. A chain // that ended at a `return` still holds the frame it returned in. let mut entered = chain.entered.take(); // Taken now, dropped last: the chain-end joins run while the // capability is still held. let access = chain.access.take(); let outcome = outcome.and_then(|returned| { // A chain ending mid-section (a `return`, with a value or // without) reads its final var back before teardown, exactly as // a completed section does // at fall-through (the walk rolls it forward; a call chain // or a task chain discards its clone), and arms the completion // flag so the frame's drop fires SECTION_FINISHED. A failure - // the read-back's included, placed on the returning block - // drops the frame unarmed. if let Some(entered) = entered.as_mut() { let line = entered.block.lua_line(blocks); entered .frame .read_var() .map_err(|error| place(error, prompt.file(), line))?; entered.frame.mark_completed(); } Ok(returned) }); // The frame drops here: the single teardown boundary. drop(entered); // The chain's tasks end with it: a live task turns a success into // `make_tasks_live_error` and is abandoned. let outcome = self.settle_owned_tasks(id, outcome); // The chain-end joins run after the settle - the abandoned tasks' // identities ended there, so their final clocks are recorded - // and before the access drops, so this chain's final clock // transitively covers everything its tasks did. if let Some(access) = &access { self.join_owned_tasks(id, access); } drop(access); // The chain's hold on its store goes with it. Every chain that // shared the store of an `execute` has ended by the time the // executed chain does, so that store is freed here. self.chains[id].ctx.release_store(); // A task chain that was holding admission slots releases them at // its end, before its owner is woken: the owner's re-acquire and // any queued sibling need the freed capacity. self.admission.release(id); // A make_determinism_error violation is fatal to the run on the spot and // never resumes into Lua as a catchable member failure: a shim // that re-raises it after its own cleanup yields would flatten // the typed error, so the outcome ends the run here, exactly as // the answer boundary does. let outcome = match outcome { Err(error) if error.code == ErrorCode::Determinism => { return ChainStep::RunEnded(Err(error)); } outcome => outcome, }; // A walk that ran off its slice, or a `return` that gave nil or no // value, produced no text. Each kind of chain delivers that in its // own way: a task's result is the empty string, the top-level // chain falls back to the shared generic completion, and a call // chain answers with no text, which its `call` returns as nil. // // A scheduler bug that strands the outcome - a missing task entry, // or a parent or waiting owner with no suspended block to take it - // fails the run loudly rather than losing it. if is_task { return match self.complete_task(id, outcome.map(Option::unwrap_or_default)) { Ok(()) => ChainStep::Continue, Err(error) => ChainStep::RunEnded(Err(error)), }; } match parent { None => ChainStep::RunEnded( outcome.map(|text| text.unwrap_or_else(|| GENERIC_COMPLETION.to_owned())), ), Some(parent_id) => match self.answer_inline(parent_id, outcome.map(Answer::Call)) { Ok(()) => ChainStep::Continue, Err(error) => ChainStep::RunEnded(Err(error)), }, } } /// Aborts one chain and everything it transitively blocks on or owns - /// its call children and the tasks it spawned (a fanout's arms among /// them; each abandoned as `owner_aborted`, its own subtree aborted in /// turn): the chain leaves the ready queue, its in-flight leaf effects /// are orphaned in the effect table, and its state drops in the /// teardown order (the suspended coroutine, then the frame unarmed - no /// `SECTION_FINISHED`). The chain's own task entry, if it is a task, is /// the caller's to settle: the owner's chain end abandons it, a cancel /// arm cancels it, and the idle cap's close ends it with its latest /// reply, having abandoned its live tasks as `owner_returned` first, so /// none is left here to abandon as `owner_aborted`. pub(super) fn abort_subtree(&mut self, id: ChainIndex) { let children: Vec = self.chains.call_children(id).collect(); for child in children { self.abort_subtree(child); } // The tasks this chain owns end with it; their outcomes have no // one to reach, so the leaked-author list is moot here. self.abandon_owned_tasks(id, AbandonReason::OwnerAborted); self.ready.retain(|ready| *ready != id); // The chain's own awaited leaf effects: one, or every call of a // `tool_calls` batch. A timer the chain owned is keyed under it // too, but `abandon_owned_tasks` above already aborted every live // one. Each tool call's identity ends as it is orphaned, so the // entries go in issue order. for effect in self.effects.awaited_by(id) { self.abort_effect(effect); } let access = { let chain = &mut self.chains[id]; // A chain aborted mid-wait leaves its set: no member's end may // wake a dead chain. chain.parked = None; chain.entered = None; chain.ctx.release_store(); chain.access.take() }; // A queued chain aborted before admission leaves both queues, and // a running task's held slots are released. self.admission.drop_aborted(id); // The chain-end join: the aborted chain's final clock still // transitively covers its tasks, for whoever joins the aborted // chain itself. if let Some(access) = &access { self.join_owned_tasks(id, access); } } /// Withdraws one in-flight leaf effect whose chain stopped waiting on /// it, because the chain is going away or a message withdrew its loop's /// round, as /// [`EffectTable::orphan`](super::effects::EffectTable::orphan) /// describes, and ends a tool call's identity through /// [`Scheduler::end_tool_call`] as its answer would, so what the tool /// already did is joined into the parked chain and anything it tries /// later is refused. pub(super) fn abort_effect(&mut self, effect: EffectId) { if let Some((chain, exec)) = self.effects.orphan(effect) { self.end_tool_call(chain, exec); } } }