# task

## 功能

创建轻量后台任务。`task(fn)` 会立即返回 `Task` 对象，任务函数在后台独立 VM 中执行；主流程可通过 `await()` 阻塞等待结果，通过 `done()` 查询完成状态，通过 `result()` 非阻塞读取结果。

后台任务采用快照传值，不共享主 VM 的数组、对象、闭包或全局变量引用。任务内部修改捕获值或全局变量快照，不会回写主流程。

## 语法

```bt
t = task(fn() {
    return 123
})

value = t.await()
done = t.done()
result = t.result()
```

## 参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| ------ | ------ | ------ | ------ | ------ |
| fn | Fn | 是 | 无 | 后台任务入口函数，只执行一次。 |

## 返回值

| 类型 | 说明 |
| ------ | ------ |
| Task | 后台任务对象，包含 await、done、result 方法。 |

## Task 方法

| 方法 | 返回值 | 说明 |
| ------ | ------ | ------ |
| await() | 任意值 | 阻塞等待任务完成；成功返回结果；任务内部 throw 时重新抛出；普通运行时错误按运行时错误返回。 |
| done() | Bool | 非阻塞判断任务是否完成。 |
| result() | 任意值 / Empty | 非阻塞读取结果；未完成返回 empty；成功返回结果；任务内部 throw 时重新抛出。 |

## 可快照类型

| 类型 | 说明 |
| ------ | ------ |
| Null | 保留显式空值。 |
| Empty | 保留缺失值；序列化到 JSON 时仍按 JSON null 输出。 |
| Int / Float / Bool / String | 按值复制。 |
| Array / Object | 递归深快照，后台 VM 和主 VM 不共享可变引用。 |

函数值、类实例、正则对象、日期对象、文件句柄、数据库连接、网络连接、设备句柄、进程句柄和原生对象不能进入任务快照，也不能作为任务结果返回。

## 示例

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

value = t.await()

// 输出：123
print value
```

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

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

// 输出：empty
print pending

// 输出：7
print value
```

```bt
x = 1

t = task(fn() {
    x = 2
    return x
})

main = x
result = t.await()

// 输出：1
print main

// 输出：2
print result
```

```bt
t = task(fn() {
    throw 'fatal'
})

value = try {
    t.await()
} catch e {
    e
}

// 输出：fatal
print value
```

## 注意事项

- `task(fn)` 只创建轻量后台任务，不引入 async fn、await 关键字、Promise、channel、timer 或共享可变状态。
- 任务函数在独立 VM 中执行，捕获变量和全局变量按创建任务时快照。
- `await()` 会阻塞当前执行流；Web 请求热路径中应谨慎使用。
- 后台任务队列和线程数有上限；队列满时 `task(fn)` 返回运行时错误。
- 可通过环境变量 `BT_TASK_WORKERS` 和 `BT_TASK_QUEUE` 调整后台任务线程数和队列长度，实际值仍会被运行时安全上限约束。