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
23pub fn logical_clock_ms() -> u64 {
25 LOGICAL_CLOCK_MS.load(Ordering::Acquire)
26}
27
28pub 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#[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 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}