Web 阻塞 API 策略

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

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

无参数。

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

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` 约束。

本节的协作式取消规则已在 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。