Documentation · Directives · API · Execution model · Security · Examples · Compatibility
ngx.semaphore is the first landed scheduler-family host set. It is a
worker-owned counting semaphore referenced through a VM-local
resource handle; it needs no script callable and does not provide the
still-blocked ngx.thread, ngx.on_abort, or ngx.run_worker_thread
callable mechanisms. The ngx.timer family landed independently through
its own worker-owned timer runtime (Sleep and timers).
Permit counters and the FIFO waiter queue live in a worker registry
(thread_local, one registry per nginx worker). The current executing VM
holds a typed resource<ngx.semaphore> entry in its own resource table.
Sync-only programs use the pooled VM path; a program using async wait uses
the request-owned VM path. A raw handle value does not transfer that entry to
another VM.
Wait futures hold worker state, an owned timeout, and a drop guard —
never a request, pool, Vm, RequestLocalCtx, or raw pointer. The
future is polled by the existing NgxAsyncBridge, and waking a waiter
only calls the eventfd-backed waker of the current request.
| OpenResty API | RustScript callable | Status | Phases | Yield | Limits | Semantic differences | Acceptance |
|---|---|---|---|---|---|---|---|
ngx.semaphore.new |
ngx::semaphore::new(count) -> resource |
adapted | PHASE_SEMAPHORE |
sync | count int 0..=1000000; ≤1024 live semaphores per worker |
Worker-owned object, not userdata; the script sees an i64 handle for its own VM table. |
tests/ngx_semaphore.rs, src/semaphore.rs |
sem:wait |
ngx::semaphore::wait(sem, timeout) -> bool |
adapted | PHASE_SEMAPHORE |
Waiting | timeout seconds; () = no timer, 0 = immediate check; shares the 1024 in-flight wait cap |
Returns true on acquire and false on timeout instead of OpenResty's nil, "timeout" pair. () (not 0) means "wait forever". FIFO: the oldest waiter wins each permit. |
tests/ngx_semaphore.rs, src/semaphore.rs |
sem:post |
ngx::semaphore::post(sem, count) -> () |
adapted | PHASE_SEMAPHORE |
sync | count int 0..=1000000 or () (=1); counter ceiling 1000000 |
Posting past the ceiling is a HostError instead of silently saturating. 0 wakes nobody. |
tests/ngx_semaphore.rs, src/semaphore.rs |
sem:count |
ngx::semaphore::count(sem) -> int |
adapted | PHASE_SEMAPHORE |
sync | — | Matches OpenResty: permits ready minus queued waiters, so a negative value is the FIFO wait depth. | tests/ngx_semaphore.rs, src/semaphore.rs |
PHASE_SEMAPHORE is access + content only. log_by_rss_file fails
configuration compile (PhaseForbidden) for every semaphore import, and
the closed Log allowlist also rejects the family and capability.
new(count):countmust be an integer in0..=1000000. Missing or invalid counts, and a worker already holding 1024 live semaphores, fail with a namedHostErrorat request time.wait(sem, timeout):timeoutis a number of seconds (fractions allowed).()waits without arming a timer (wait forever);0is an immediate, non-blocking check that returnsfalsewhen no permit is free; a positive number arms the owned timeout. Negative,NaN, infinite, and non-number timeouts are rejected before the future is submitted. RustScript adds()for an unbounded wait; OpenResty and RustScript both use0for the immediate attempt.post(sem, count):countis an integer or()(one permit). Negative, fractional, and non-number counts are rejected.0is a no-op.count + currentabove 1000000 is aHostError.count(sem): read-only.- The catalog types the handle as
resource<ngx.semaphore>, so an integer handle is a configuration compile error, not a runtime lookup. Closed or released entries still fail closed at runtime.
| Event | Required behavior |
|---|---|
| Permit available at submit | The initial bridge poll returns Ready; the request never suspends. |
| No permit | The waiter joins the FIFO queue, the request returns NGX_AGAIN, and DEFAULT_MAX_IN_FLIGHT (1024) is reserved exactly once. |
post from another request / the same worker |
At most min(permits, queued) front waiters with registered wakers are woken; each grant cascades the next wake. |
| Timeout | The wait resolves with false after the timeout elapses, releases the reservation, and removes its FIFO entry. No permit is consumed. A 0 timeout resolves as soon as the FIFO front has no permit. |
| Client close / 499 / request end | The bridge drops the future; the drop guard removes the FIFO entry exactly once and the reservation is released. |
Typed cancellation (OperationCancelReason) |
Uses the existing bridge request_cancel_op/poll_cancel_op protocol; no new cancellation protocol or eventfd. |
Worker exit_process |
Live semaphores are closed, every waiter is woken, the registry is emptied, and parked waits fail closed. Ids are never reused. |
| VM-local handle release | Each new creates one VM-local handle. Releasing that handle removes the worker entry; repeated release is a no-op. This is a single-handle lifecycle. An in-flight wait keeps its own state alive and cannot observe a recycled identity. |
| Double cleanup | Deregistration is idempotent: a granted waiter already left the queue, and a second release is a no-op. Permits are consumed only at grant time, so cleanup can never leak or double-release one. |
| Budget | Value |
|---|---|
| Permits per semaphore | 1000000 (MAX_SEMAPHORE_COUNT) |
| Live semaphores per worker | 1024 (MAX_LIVE_SEMAPHORES) |
| In-flight semaphore waits | Shared DEFAULT_MAX_IN_FLIGHT (1024) per worker |
| Resource table | pd-vm default 1024 entries per VM |
See also: API index · Phase sets · Scheduler design · Hard caps