# 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

```bt
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

```bt
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

```bt
t = task(fn(value) {
    sleep(100)
    return value + 1
}, 122)

value = t.await()

// Output: 123
print value
```

```bt
t = task(fn() {
    sleep(100)
    return 7
})

pending = t.result()
sleep(200)
value = t.result()

// Output: empty
print pending

// Output: 7
print value
```

```bt
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
```

```bt
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()` and `task_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](/en/docs/web/io-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_WORKERS` and `BT_TASK_QUEUE`. The actual values will still be constrained by the runtime safety upper limit.