Web blocking API strategy

Web blocking API strategy

AI Markdown

Web blocking API strategy

Function

Describes the rules for operating slow I/O, blocking waits, and long-term background capabilities in the context of web requests.

The web request script will enter the BT process-level blocking pool for execution as a whole to avoid fs, short sleep(), template compilation, synchronization script logic, etc. from blocking Tokio Web workers. The number of threads, queue length, and default wait time of the blocking pool are controlled by the BT_IO_* configuration.

Syntax

Parameters

No parameters.

Return value

This page is a rule description and does not provide independent function return values.

Web request rules

APIBehavior in Web RequestsBoundaries
sleep(ms)Allow short sleep.ms cannot exceed BT_IO_TIMEOUT_MS, the default is 30000 milliseconds.
pause()Rejected.There is no interactive terminal for web requests.
fs.*Allowed.The entire request script runs in the blocking pool, subject to BT_IO_BLOCKING_WORKERS, BT_IO_BLOCKING_QUEUE, BT_IO_TIMEOUT_MS.
process.status() / process.output() / process.child() / process.wait()Rejected.These operations may wait synchronously on external processes or fork long-term child processes.
reqwest.send()Allowed.Using the shared I/O runtime, the default time for a single request is 30000 milliseconds; it can be set by timeout(ms), but the overall web request is still subject to BT_IO_TIMEOUT_MS.
mysql.all() / mysql.one() / mysql.exec()Allowed.Using the shared I/O runtime and MySQL query timeouts, web requests overall are still subject to BT_IO_TIMEOUT_MS.
task(fn, ...args)Allow background task submission.Task.on_done(), Task.await(), task_all(), task_race() rejected in web request.
device.*Allowed.Serial port opening, reading and writing must rely on the timeout in the device configuration, and the entire web request is subject to BT_IO_TIMEOUT_MS.

Code Example

Request deadline configuration

The cooperative cancellation rules in this section are available on main for the next release. Published 1.1.4 only stops waiting when the request timeout expires.

VariableTypeRequiredDefaultRangeMeaning
BT_IO_TIMEOUT_MSInteger environment variableNo30000Positive millisecondsOne deadline covering the blocking queue and script execution, shared by nested functions, includes, templates, sleep, and shared asynchronous I/O.
BT_IO_BLOCKING_WORKERSInteger environment variableNoLogical CPU count1..64 when configuredMaximum number of blocking workers shared by requests.
BT_IO_BLOCKING_QUEUEInteger environment variableNo2561..8192Maximum queued jobs; a full queue rejects new work.

Notes

  • Expired queued scripts are skipped before user code runs. Running BT bytecode checks the deadline at bounded instruction intervals and before function calls. The deadline is cooperative, not a hard real-time guarantee.
  • sleep(ms) still rejects durations above BT_IO_TIMEOUT_MS; otherwise it stops at the remaining request deadline. HTTP/MySQL waits use the smaller of their operation timeout and the remaining request time. Dropping the request waiter also signals cancellation.
  • A timeout returns an HTTP error. BT cannot safely force-stop a native filesystem/device/FFI call or an extension host call already in progress; the worker is released after that call returns and cancellation is observed. Configure those operations' own timeouts or isolate long-running native work in a separate process.
  • Cancellation does not undo file writes, database changes, sent network requests or other effects already performed. Explicitly submitted task(...) background jobs retain their independent lifecycle.
  • A full queue returns an English error beginning with The I/O blocking task queue is full.
  • CLI and desktop execution without a Web request budget retain their existing behavior.
  • Run examples/web-blocking-policy/main.bt for API policy examples. Contributors can run python tools/quality/verify-web-deadlines.py --bt target/debug/bt.exe from the runtime repository on Windows; use target/debug/bt on Unix.