task
task
Function
Create lightweight background tasks. task(fn, ...args) will immediately return the Task object, and the task function is executed in a background independent VM; the main process can block and wait for the result through await(), query the completion status through done(), read the result non-blockingly through result(), or use on_done(fn) to read the result in a long-term VM Register the completion callback in the event loop.
Background tasks use snapshots to pass values and do not share arrays, objects, closures or global variable references of the main VM. Explicit parameters, closure captures, and possibly accessed global variables are all snapshotted when the task is created.
Syntax
t = task(fn(value) { return value + 1 }, 6) value = t.await() done = t.done() result = t.result()
Parameters
| Parameters | Type | Required | Default value | Description |
|---|---|---|---|---|
| fn | Fn | Yes | None | Background task entry function, executed only once. |
| ...args | Any snapshottable value | No | None | Explicit parameters passed to the task entry function, snapshot when creating the task. |
Return value
| Type | Description |
|---|---|
| Task | Background task object, including await, done, result, on_done methods. |
Task method
| Method | Return Value | Description |
|---|---|---|
| await() | Any value | Blocks and waits for the task to complete; returns the result successfully; rethrows when the task throws internally; ordinary runtime errors are returned as runtime errors. |
| done() | Bool | Non-blocking judgment of whether the task is completed. |
| result() | Any value / Empty | Non-blocking read result; return empty if not completed; return result successfully; rethrow when task internal throw occurs. |
| on_done(fn) | Task | Register the completion callback and return the current Task to facilitate chain calls. |
on_done callback
t.on_done(fn(result, err, status) { if status != 'success' { return empty } // Output: 123 print result })
| Parameters | Type | Description |
|---|---|---|
| result | Any value / Empty | Return value when the task succeeds; empty when the task fails or throw. |
| err | Any value / String / Empty | The value thrown when the task throws; the error text when it fails; and empty when it succeeds. |
| status | String | success, throw or failed. |
on_done() The callback is executed on the VM thread that registered it, and will not be executed directly on the background task thread. CLI scripts and desktop long-lived VMs dispatch callbacks at event boundaries after the main process ends; web request VMs are short-lived and cannot be registered on_done().
Available snapshot types
| Type | Description |
|---|---|
| Null | Keep explicit null values. |
| Empty | Keep missing values; still output as JSON null when serialized to JSON. |
| Int / Float / Bool / String | Copy by value. |
| Array / Object | Recursive deep snapshot, background VM and main VM do not share mutable references. |
Function values, class instances, regular objects, date objects, file handles, database connections, network connections, device handles, process handles, and native objects cannot enter the task snapshot, nor can they be returned as task results.
Example
t = task(fn(value) { sleep(100) return value + 1 }, 122) value = t.await() // Output: 123 print value
t = task(fn() { sleep(100) return 7 }) pending = t.result() sleep(200) value = t.result() // Output: empty print pending // Output: 7 print value
data = {count: 1} t = task(fn(item) { item.count = 9 return item.count }, data) data.count = 2 result = t.await() // Output: 2 print data.count // Output: 9 print result
task(fn() { return 123 }).on_done(fn(result, err, status) { if status == 'success' { // Output: 123 print result } })
Notes
-
task(fn, ...args)Only create lightweight background tasks and do not introduce async fn, await keyword, Promise, channel or shared mutable state. - Task functions are executed in a separate VM, and explicit parameters, capture variables, and global variables are snapshotted when the task is created.
-
await(),task_all()andtask_race()block the current execution flow; these synchronous wait methods are rejected directly in the web request context. -
Task.on_done()Can only be used in CLI-resident scripts and desktop long-lived VMs, not in web request contexts. - Submissions of
task(fn, ...args)are allowed in web requests, but callbacks cannot be registered within the request or wait for completion; for complete rules, see: Web Blocking API Policy. - The background task queue, number of threads, snapshot size, completion subscription and callback table have upper limits; exceeding the upper limit will return a runtime error.
- The number of background task threads and queue length can be adjusted through the environment variables
BT_TASK_WORKERSandBT_TASK_QUEUE. The actual values will still be constrained by the runtime safety upper limit.