Documentation · Directives · API · Execution model · Security · Examples · Compatibility
| OpenResty API | RustScript callable | Status | Phases | Yield | Limits | Semantic differences | Acceptance |
|---|---|---|---|---|---|---|---|
ngx.sleep |
ngx::sleep(seconds: number) -> () |
adapted | SLEEP_PHASES |
Waiting | in-flight 1024; rejects negative / NaN / infinity / overflow | Seconds (int or float), not milliseconds. Tokio timer; completion via HostFuture -> waker -> eventfd -> worker-main-thread resume. Client close during wait is HTTP 499. |
tests/vm_sleep.rs, tests/host_catalog.rs, tests/access_async.rs, tests/lifecycle.rs, tests/nginx_integration.py |
ngx.sleep (legacy ms form) |
ngx::sleep_ms(ms: int) -> () |
adapted | SLEEP_PHASES |
Waiting | in-flight 1024; ms >= 0 |
Not an OpenResty name. Integer milliseconds for scripts written before the seconds migration. Same Waiting path as ngx::sleep. |
tests/vm_sleep.rs, tests/access_async.rs, tests/request_driver.rs, tests/lifecycle.rs |
Worker-owned OpenResty-style timers. A registration survives the request that created it; the callback runs on a timer-owned VM.
| OpenResty API | RustScript callable | Status | Phases | Yield | Limits | Semantic differences | Acceptance |
|---|---|---|---|---|---|---|---|
ngx.timer.at |
ngx::timer::at(seconds: number, callback: fn(bool) -> ()) -> () |
adapted | access, content | sync (the callback runs later) | checked Duration; negative/NaN/infinite rejected; TimerConfig.max_pending = 1024, worker pool 1024 |
Seconds (int or float), not milliseconds. The callback is consumed (TakeOwned). premature=false on normal expiry. |
tests/ngx_scheduler_contract.rs, tests/ngx_timer.rs, tests/timer_nginx.rs |
ngx.timer.every |
ngx::timer::every(seconds: number, callback: fn(bool) -> ()) -> () |
adapted | access, content | sync (the callback runs later) | checked Duration; interval > 0 required; same caps |
Rounds serialize: the next deadline is scheduled only after the previous round is terminal, its identity rotates to a fresh generation, and mutable capture cells persist between rounds. | tests/ngx_timer.rs, tests/timer_nginx.rs |
ngx.timer.pending_count |
ngx::timer::pending_count() -> int |
adapted | access, content | sync | none | Registrations waiting to begin, or waiting for a running slot. | tests/ngx_timer.rs, tests/timer_nginx.rs |
ngx.timer.running_count |
ngx::timer::running_count() -> int |
adapted | access, content | sync | TimerConfig.max_running = 256 |
Live callback rounds, including callbacks parked on async host work. | tests/ngx_timer.rs, tests/timer_nginx.rs |
Binding and lifetime:
- The two registration hosts consume their callback through
HostParamPassing::TakeOwned; they are the only catalogued callables. A program that imports a timer host is bound from the timer-host registry (ngx_host_registry), and callback VMs spawn from that same registry. - Every accepted registration owns one ordinary
RequestIdentityand one fake request in a bounded worker pool (1024, the capacity of the sharedrequest_state::IdentityRegistry). The deadline task holds only aCompletionSenderand that identity and wakes through the worker's existing eventfd; no second identity, eventfd, or queue exists. - Identity: fake request ids are worker-unique, tagged out of the real
request-id space (
timer::FAKE_REQUEST_ID_TAG), and never reused, so a timer identity can never equal a request identity and the two dispatch paths stay disjoint without a reserved generation. Aneveryround retires its identity on completion and re-arms under a fresh monotonically advancing generation for the same fake request id, so a stale or duplicate wake of a finished round is ignored and can never start the pending round early or break the interval. - Callback VM: private execution instance, own
NgxAsyncBridge, script bytecode on the worker main thread only. - Callback phase:
NgxPhase::Timerwith a log-onlyAllowedOpsallowlist. Log,ngx::sleep/sleep_ms, outbound async I/O, the shared dictionary, the semaphore family, and the timer family work. Request headers/body/raw,ngx.ctx, response output, and control (ngx::exit,ngx::redirect) fail closed and are reported through the worker log. The standard I/O, HTTP, and SQLite policies are per-VM and are not inherited by a callback VM. - Errors: a callback failure is reported once through the worker log;
atterminates,everystays eligible for its next round. - Shutdown and reload: worker exit runs pending callbacks once with
premature=true(including a pendingeveryround, which is not rescheduled), cancels live callbacks, stops furthereveryrounds, and releases every callback VM. A reload does not migrate timers; new workers start with zero timers. Creating-request cleanup never cancels a timer. - Configuration: registration is rejected in
log_by_rss_fileat configuration compile (PhaseForbidden), and the barengx::timermarker is not a callable.
See also: API index · Phase sets · Cross-cutting adaptations · Hard caps