Skip to main content

vibe/task_scheduler/
registry.rs

1pub(super) use super::retention::retained_bytes;
2use crate::{
3    error::{DiagCode, Diagnostic},
4    span::Span,
5    value::Value,
6};
7use std::{
8    collections::BTreeMap,
9    sync::{
10        atomic::{AtomicU64, Ordering},
11        Arc, Mutex, OnceLock,
12    },
13};
14
15const MAX_SCOPE_TASKS: usize = 256;
16const MAX_PROCESS_TASKS: usize = 4096;
17const MAX_SCOPE_BYTES: usize = 8 * 1024 * 1024;
18const MAX_PROCESS_BYTES: usize = 64 * 1024 * 1024;
19static NEXT_SCOPE: AtomicU64 = AtomicU64::new(1);
20static NEXT_TASK: AtomicU64 = AtomicU64::new(1);
21static LOGICAL_CLOCK_MS: AtomicU64 = AtomicU64::new(0);
22
23/// Current deterministic logical/Lamport clock value in milliseconds.
24pub fn logical_clock_ms() -> u64 {
25    LOGICAL_CLOCK_MS.load(Ordering::Acquire)
26}
27
28/// Advance the deterministic logical/Lamport clock by `delta_ms` milliseconds.
29pub fn advance_logical_clock_ms(delta_ms: u64) -> u64 {
30    LOGICAL_CLOCK_MS
31        .fetch_add(delta_ms, Ordering::AcqRel)
32        .saturating_add(delta_ms)
33}
34#[derive(Default)]
35pub(super) struct TaskRegistry {
36    entries: Vec<Entry>,
37}
38
39impl TaskRegistry {
40    pub(super) fn get_mut(&mut self, id: &u64) -> Option<&mut Entry> {
41        let idx = self.entries.binary_search_by_key(id, |entry| entry.id).ok()?;
42        Some(&mut self.entries[idx])
43    }
44
45    #[cfg(test)]
46    pub(super) fn contains_key(&self, id: &u64) -> bool {
47        self.entries.binary_search_by_key(id, |entry| entry.id).is_ok()
48    }
49
50    pub(super) fn len(&self) -> usize {
51        self.entries.len()
52    }
53
54    pub(super) fn values(&self) -> std::slice::Iter<'_, Entry> {
55        self.entries.iter()
56    }
57
58    pub(super) fn insert(&mut self, id: u64, entry: Entry) {
59        if self.entries.last().map_or(true, |last| last.id < id) {
60            self.entries.push(entry);
61            return;
62        }
63        match self.entries.binary_search_by_key(&id, |e| e.id) {
64            Ok(idx) => self.entries[idx] = entry,
65            Err(idx) => self.entries.insert(idx, entry),
66        }
67    }
68
69    pub(super) fn retain(&mut self, mut keep: impl FnMut(&u64, &Entry) -> bool) {
70        self.entries.retain(|entry| keep(&entry.id, entry));
71    }
72}
73
74static REGISTRY: OnceLock<Mutex<TaskRegistry>> = OnceLock::new();
75pub(super) fn registry() -> &'static Mutex<TaskRegistry> {
76    REGISTRY.get_or_init(Default::default)
77}
78pub(super) fn error(span: Span, message: &str) -> Diagnostic {
79    Diagnostic::new(DiagCode::E400, span, message)
80}
81
82/// Opaque runtime ownership, independent of authored owner fields and human authority.
83#[derive(Clone, Debug)]
84pub struct TaskScope(Arc<ScopeOwner>);
85#[derive(Debug)]
86struct ScopeOwner {
87    id: u64,
88}
89impl Default for TaskScope {
90    fn default() -> Self {
91        Self(Arc::new(ScopeOwner {
92            id: NEXT_SCOPE.fetch_add(1, Ordering::Relaxed),
93        }))
94    }
95}
96impl Drop for ScopeOwner {
97    fn drop(&mut self) {
98        if let Ok(mut tasks) = registry().lock() {
99            tasks.retain(|_, entry| entry.owner != self.id);
100        }
101    }
102}
103#[derive(Clone, Copy, Debug, PartialEq, Eq)]
104pub(super) enum State {
105    Pending,
106    Running,
107    Completed,
108    Cancelled,
109    TimedOut,
110    Failed,
111}
112impl State {
113    pub(super) fn label(self) -> &'static str {
114        match self {
115            Self::Pending => "pending",
116            Self::Running => "running",
117            Self::Completed => "completed",
118            Self::Cancelled => "cancelled",
119            Self::TimedOut => "timed_out",
120            Self::Failed => "failed",
121        }
122    }
123    pub(super) fn terminal(self) -> bool {
124        !matches!(self, Self::Pending | Self::Running)
125    }
126}
127#[derive(Clone)]
128pub(super) struct Entry {
129    pub(super) id: u64,
130    owner: u64,
131    pub(super) code: String,
132    pub(super) state: State,
133    created_tick: u64,
134    deadline_tick: Option<u64>,
135    pub(super) cancel_requested: bool,
136    timeout_requested: bool,
137    pub(super) result: Option<Value>,
138    pub(super) failure: Option<String>,
139    pub(super) retained_bytes: usize,
140}
141pub fn extract_task_id(rec: &BTreeMap<String, Value>) -> Option<u64> {
142    match rec.get("task_id") {
143        Some(Value::U64(id)) if *id > 0 => Some(*id),
144        Some(Value::I64(id)) if *id > 0 => Some(*id as u64),
145        _ => None,
146    }
147}
148pub fn is_task_record(rec: &BTreeMap<String, Value>) -> bool {
149    rec.get("__task") == Some(&Value::Bool(true))
150        || extract_task_id(rec).is_some()
151        || rec.contains_key("status")
152}
153pub(super) fn record(entry: &Entry) -> Value {
154    let mut out = BTreeMap::new();
155    out.insert("__task".into(), Value::Bool(true));
156    out.insert("task_id".into(), Value::U64(entry.id));
157    out.insert("status".into(), Value::String(entry.state.label().into()));
158    out.insert(
159        "cancelled".into(),
160        Value::Bool(entry.state == State::Cancelled),
161    );
162    out.insert(
163        "timed_out".into(),
164        Value::Bool(entry.state == State::TimedOut),
165    );
166    out.insert(
167        "cancel_requested".into(),
168        Value::Bool(entry.cancel_requested),
169    );
170    out.insert(
171        "cancel_acknowledged".into(),
172        Value::Bool(matches!(entry.state, State::Cancelled | State::TimedOut)),
173    );
174    out.insert(
175        "deadline_expired".into(),
176        Value::Bool(entry.timeout_requested),
177    );
178    out.insert("scheduler_registered".into(), Value::Bool(true));
179    out.insert("scheduler_contacted".into(), Value::Bool(true));
180    out.insert(
181        "live_job_joined".into(),
182        Value::Bool(entry.state == State::Completed),
183    );
184    out.insert(
185        "execution_qualification".into(),
186        Value::String("local_deferred_synchronous_ast_task".into()),
187    );
188    if let Some(result) = &entry.result {
189        out.insert("result".into(), result.clone());
190    }
191    if let Some(failure) = &entry.failure {
192        out.insert("error".into(), Value::String(failure.clone()));
193    }
194    Value::Record(out)
195}
196pub(super) fn owned<'a>(
197    scope: &TaskScope,
198    tasks: &'a mut TaskRegistry,
199    value: &Value,
200    span: Span,
201) -> Result<&'a mut Entry, Diagnostic> {
202    let Value::Record(rec) = value else {
203        return Err(error(
204            span,
205            "task operation requires a scoped task record; integer IDs are not handles",
206        ));
207    };
208    let id = extract_task_id(rec).ok_or_else(|| error(span, "task record has no task_id"))?;
209    let entry = tasks
210        .get_mut(&id)
211        .ok_or_else(|| error(span, "task is unknown or its runtime scope was disposed"))?;
212    if entry.owner != scope.0.id {
213        return Err(error(span, "task belongs to a different runtime scope"));
214    }
215    Ok(entry)
216}
217pub(super) fn refresh_observer(entry: &mut Entry) {
218    if entry.state.terminal() {
219        return;
220    }
221    if entry
222        .deadline_tick
223        .is_some_and(|deadline| logical_clock_ms() >= deadline)
224    {
225        entry.timeout_requested = true;
226        entry.cancel_requested = true;
227    }
228    // Observers cannot acknowledge a running native callback has stopped.
229    if entry.state == State::Pending {
230        acknowledge(entry);
231    }
232}
233pub(super) fn acknowledge(entry: &mut Entry) {
234    if entry.state.terminal() {
235        return;
236    }
237    if entry.timeout_requested {
238        entry.state = State::TimedOut;
239    } else if entry.cancel_requested {
240        entry.state = State::Cancelled;
241    }
242}
243pub(super) fn executor_checkpoint(entry: &mut Entry) {
244    refresh_observer(entry);
245    if entry.state == State::Running {
246        acknowledge(entry);
247    }
248}
249pub(super) fn spawn(scope: &TaskScope, code: &str, span: Span) -> Result<Value, Diagnostic> {
250    if code.trim().is_empty() || code.len() > 65_536 {
251        return Err(error(span, "task source must contain 1..65536 UTF-8 bytes"));
252    }
253    let mut tasks = registry()
254        .lock()
255        .map_err(|_| error(span, "task registry is poisoned"))?;
256    if tasks.len() >= MAX_PROCESS_TASKS
257        || tasks
258            .values()
259            .filter(|entry| entry.owner == scope.0.id)
260            .count()
261            >= MAX_SCOPE_TASKS
262    {
263        return Err(error(
264            span,
265            "task registry capacity exhausted; dispose the owning environment to release its tasks",
266        ));
267    }
268    admit_bytes(scope, &tasks, code.len(), span)?;
269    let id = NEXT_TASK.fetch_add(1, Ordering::Relaxed);
270    let entry = Entry {
271        id,
272        owner: scope.0.id,
273        code: code.into(),
274        state: State::Pending,
275        created_tick: logical_clock_ms(),
276        deadline_tick: None,
277        cancel_requested: false,
278        timeout_requested: false,
279        result: None,
280        failure: None,
281        retained_bytes: code.len(),
282    };
283    let output = record(&entry);
284    tasks.insert(id, entry);
285    Ok(output)
286}
287pub(super) fn admit_bytes(
288    scope: &TaskScope,
289    tasks: &TaskRegistry,
290    bytes: usize,
291    span: Span,
292) -> Result<(), Diagnostic> {
293    let scope_bytes: usize = tasks
294        .values()
295        .filter(|entry| entry.owner == scope.0.id)
296        .map(|entry| entry.retained_bytes)
297        .sum();
298    let process_bytes: usize = tasks.values().map(|entry| entry.retained_bytes).sum();
299    if bytes > MAX_SCOPE_BYTES.saturating_sub(scope_bytes)
300        || bytes > MAX_PROCESS_BYTES.saturating_sub(process_bytes)
301    {
302        return Err(error(
303            span,
304            "task retention budget exhausted (8 MiB per scope / 64 MiB per process)",
305        ));
306    }
307    Ok(())
308}
309pub(super) fn status(scope: &TaskScope, value: &Value, span: Span) -> Result<Value, Diagnostic> {
310    let mut tasks = registry()
311        .lock()
312        .map_err(|_| error(span, "task registry is poisoned"))?;
313    let entry = owned(scope, &mut tasks, value, span)?;
314    refresh_observer(entry);
315    Ok(record(entry))
316}
317pub(super) fn cancel(scope: &TaskScope, value: &Value, span: Span) -> Result<Value, Diagnostic> {
318    let mut tasks = registry()
319        .lock()
320        .map_err(|_| error(span, "task registry is poisoned"))?;
321    let entry = owned(scope, &mut tasks, value, span)?;
322    refresh_observer(entry);
323    let terminal = entry.state.terminal();
324    if !terminal {
325        entry.cancel_requested = true;
326        if entry.state == State::Pending {
327            entry.state = State::Cancelled;
328        }
329    }
330    let Value::Record(mut out) = record(entry) else {
331        unreachable!()
332    };
333    out.insert(
334        "already_committed".into(),
335        Value::Bool(entry.state == State::Completed),
336    );
337    out.insert("cancel_requested".into(), Value::Bool(true));
338    out.insert(
339        "cancellation_request_accepted".into(),
340        Value::Bool(!terminal),
341    );
342    out.insert(
343        "live_job_cancelled".into(),
344        Value::Bool(!terminal && entry.state == State::Cancelled),
345    );
346    Ok(Value::Record(out))
347}
348pub(super) fn timeout(
349    scope: &TaskScope,
350    value: &Value,
351    ms: i64,
352    span: Span,
353) -> Result<Value, Diagnostic> {
354    let mut tasks = registry()
355        .lock()
356        .map_err(|_| error(span, "task registry is poisoned"))?;
357    let entry = owned(scope, &mut tasks, value, span)?;
358    if !entry.state.terminal() {
359        let deadline = entry
360            .created_tick
361            .checked_add(ms.max(0) as u64)
362            .ok_or_else(|| error(span, "task timeout exceeds the logical clock range"))?;
363        entry.deadline_tick = Some(entry.deadline_tick.map_or(deadline, |old| old.min(deadline)));
364        refresh_observer(entry);
365    }
366    Ok(record(entry))
367}
368pub(crate) fn checkpoint(scope: &TaskScope, id: u64, span: Span) -> Result<(), Diagnostic> {
369    let mut tasks = registry()
370        .lock()
371        .map_err(|_| error(span, "task registry is poisoned"))?;
372    let entry = tasks
373        .get_mut(&id)
374        .filter(|entry| entry.owner == scope.0.id)
375        .ok_or_else(|| error(span, "active task lost its runtime scope"))?;
376    executor_checkpoint(entry);
377    if entry.state != State::Running {
378        return Err(error(
379            span,
380            "task cancelled or deadline expired; prior external effects may require reconciliation",
381        ));
382    }
383    Ok(())
384}
385
386#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
387pub struct TaskRegistrySummary {
388    pub total: u64,
389    pub pending: u64,
390    pub running: u64,
391    pub completed: u64,
392    pub cancelled: u64,
393    pub timed_out: u64,
394    pub failed: u64,
395}
396pub fn registry_summary() -> TaskRegistrySummary {
397    let mut summary = TaskRegistrySummary::default();
398    if let Ok(tasks) = registry().lock() {
399        summary.total = tasks.len() as u64;
400        for entry in tasks.values() {
401            match entry.state {
402                State::Pending => summary.pending += 1,
403                State::Running => summary.running += 1,
404                State::Completed => summary.completed += 1,
405                State::Cancelled => summary.cancelled += 1,
406                State::TimedOut => summary.timed_out += 1,
407                State::Failed => summary.failed += 1,
408            }
409        }
410    }
411    summary
412}