Skip to main content

kernel_apis/
tasks.rs

1//! The task operations host modules use (TS `NativeHostApi` of `ultron/rlm/host-module.ts`). Tasks and results are
2//! the TS JSON shapes (`NativeTask`, `NativeResult` of `ultron/rlm/task-store.ts`) so modules port unchanged.
3//! Identity comes from the calling lane, never from a payload.
4
5use serde_json::Value;
6
7pub trait TaskHost: Send + Sync {
8    /// Task that owns `lane`, or `None` for the root lane.
9    fn caller_task_id(&self, lane: &str) -> Option<String>;
10    /// Lane a live task ran on, if any.
11    fn task_lane(&self, task_id: &str) -> Option<String>;
12    /// Execution strategy of a registered definition ("deterministic" | "predict" | "rlm").
13    fn strategy(&self, definition: &str) -> Result<String, String>;
14    /// Every task of the session (`NativeTask` objects: id, parentId, definition, state, ...).
15    fn tasks(&self) -> Result<Vec<Value>, String>;
16    /// Admits `request` (`{definition, input, model?, key?, timeoutMs?, lane?}`) as a child of `parent`.
17    fn spawn(&self, request: &Value, parent: Option<&str>) -> Result<Value, String>;
18    /// Blocks until the task's durable terminal result (`NativeResult`).
19    fn result(&self, task_id: &str) -> Result<Value, String>;
20    fn cancel(&self, task_id: &str, reason: &str) -> Result<Value, String>;
21    /// Queues a steering message into a running task's lane; false when it has no live lane.
22    fn steer(&self, task_id: &str, message: &str) -> Result<bool, String>;
23    /// Usage status of the caller's root.
24    fn usage(&self) -> Result<Option<Value>, String> {
25        Ok(None)
26    }
27    fn now(&self) -> i64;
28    /// Keeps a lane's Python kernel alive for `holder`; false when the host has no pool or no pin capacity left.
29    fn pin_lane(&self, _lane: &str, _holder: &str) -> bool {
30        false
31    }
32    fn unpin_lane(&self, _lane: &str, _holder: &str) {}
33}
34
35/// A host with only the root lane and no task runtime: every task operation that needs one is refused.
36pub struct RootOnly {
37    pub now: crate::util::Clock,
38}
39
40const NO_TASKS: &str = "Ultron task runtime is not available in this host";
41
42impl TaskHost for RootOnly {
43    fn caller_task_id(&self, _lane: &str) -> Option<String> {
44        None
45    }
46    fn task_lane(&self, _task_id: &str) -> Option<String> {
47        None
48    }
49    fn strategy(&self, definition: &str) -> Result<String, String> {
50        Err(format!("Unknown Ultron definition: {definition}"))
51    }
52    fn tasks(&self) -> Result<Vec<Value>, String> {
53        Ok(Vec::new())
54    }
55    fn spawn(&self, _request: &Value, _parent: Option<&str>) -> Result<Value, String> {
56        Err(NO_TASKS.into())
57    }
58    fn result(&self, _task_id: &str) -> Result<Value, String> {
59        Err("Unknown Ultron task".into())
60    }
61    fn cancel(&self, _task_id: &str, _reason: &str) -> Result<Value, String> {
62        Err("Unknown Ultron task".into())
63    }
64    fn steer(&self, _task_id: &str, _message: &str) -> Result<bool, String> {
65        Ok(false)
66    }
67    fn now(&self) -> i64 {
68        (self.now)()
69    }
70}