# Web 阻塞 API 策略

## 功能

说明 Web 请求上下文中慢 I/O、阻塞等待和长期后台能力的运行规则。

Web 请求脚本会整体进入 BT 进程级 blocking pool 执行，避免 `fs`、短 `sleep()`、模板编译、同步脚本逻辑等阻塞 Tokio Web worker。blocking pool 的线程数、队列长度和默认等待时间由 `BT_IO_*` 配置控制。

## 语法

```bt
// 查看当前 I/O 运行边界配置
stats = BT.stats().io
```

## 参数

无参数。

## 返回值

该页面是规则说明，不提供独立函数返回值。

## Web 请求规则

| API | Web 请求中行为 | 边界 |
| ------ | ------ | ------ |
| `sleep(ms)` | 允许短休眠。 | `ms` 不能超过 `BT_IO_TIMEOUT_MS`，默认 30000 毫秒。 |
| `pause()` | 拒绝。 | Web 请求没有交互式终端。 |
| `fs.*` | 允许。 | 请求脚本整体运行在 blocking pool，受 `BT_IO_BLOCKING_WORKERS`、`BT_IO_BLOCKING_QUEUE`、`BT_IO_TIMEOUT_MS` 约束。 |
| `process.status()` / `process.output()` / `process.child()` / `process.wait()` | 拒绝。 | 这些操作可能同步等待外部进程或派生长期子进程。 |
| `reqwest.send()` | 允许。 | 使用共享 I/O runtime，单次请求默认 30000 毫秒；可用 `timeout(ms)` 设置，但 Web 请求整体仍受 `BT_IO_TIMEOUT_MS` 约束。 |
| `mysql.all()` / `mysql.one()` / `mysql.exec()` | 允许。 | 使用共享 I/O runtime 和 MySQL 查询超时，Web 请求整体仍受 `BT_IO_TIMEOUT_MS` 约束。 |
| `task(fn, ...args)` | 允许提交后台任务。 | `Task.on_done()`、`Task.await()`、`task_all()`、`task_race()` 在 Web 请求中拒绝。 |
| `device.*` | 允许。 | 串口打开和读写必须依赖设备配置中的超时，Web 请求整体受 `BT_IO_TIMEOUT_MS` 约束。 |

## 代码示例

```bt
web.header('Content-Type', 'text/plain; charset=utf-8')

sleep(5)

// 输出：ok
print 'ok'
```

```bt
web.header('Content-Type', 'text/plain; charset=utf-8')

task(fn() {
    return 1
}).await()

// 输出：不会执行到这里
print 'done'
```

## 请求执行期限配置

本节的协作式取消规则已在 `main` 实现，将随下一版本发布。已发布的 1.1.4 在请求超时后仅停止等待结果。

| 变量 | 类型 | 是否必填 | 默认值 | 有效范围 | 含义 |
| ------ | ------ | ------ | ------ | ------ | ------ |
| `BT_IO_TIMEOUT_MS` | 整数环境变量 | 否 | `30000` | 正整数毫秒 | 包含 blocking 队列和脚本执行的统一期限，嵌套函数、include、模板、`sleep` 与共享异步 I/O 共用该期限。 |
| `BT_IO_BLOCKING_WORKERS` | 整数环境变量 | 否 | 逻辑 CPU 数量 | 显式配置时 `1..64` | 请求共用的 blocking worker 数量上限。 |
| `BT_IO_BLOCKING_QUEUE` | 整数环境变量 | 否 | `256` | `1..8192` | 排队任务上限，队列已满时拒绝新任务。 |

## 注意事项

- 过期排队脚本在执行用户代码前直接跳过。正在运行的 BT 字节码以有界指令间隔及在函数调用前检查期限。这是协作式停止，不是硬实时保证。
- `sleep(ms)` 仍拒绝超过 `BT_IO_TIMEOUT_MS` 的时长，其他休眠会在请求剩余期限到达时停止。HTTP/MySQL 等待采用操作自身超时与请求剩余时间中的较小值。请求等待方被销毁时也会发出取消信号。
- 超时会返回 HTTP 错误。BT 无法安全强制中断已经执行中的原生文件系统、设备、FFI 调用或扩展宿主调用；该调用返回并观察到取消后才释放工作线程。应配置这些操作自身的超时，或把长期原生工作隔离到独立进程。
- 取消不回滚已完成的文件写入、数据库变更、已发送网络请求或其他副作用。显式提交的 `task(...)` 后台任务保留独立生命周期。
- 队列已满时返回以 `The I/O blocking task queue is full` 开头的英文错误。
- 未绑定 Web 请求期限的 CLI 和桌面执行保持原有行为。
- 可运行 `examples/web-blocking-policy/main.bt` 查看 API 策略示例。贡献者可在 Windows 的运行时仓库执行 `python tools/quality/verify-web-deadlines.py --bt target/debug/bt.exe`，Unix 对应路径为 `target/debug/bt`。