Waiting without blocking
A worker of nginx serves many connections at once from one event loop. A
handler that waits in a blocking call, such as sleep or a socket read,
stops the whole worker. Nginx::Async.sleep and
Nginx::Async::HTTP.sub_request wait through nginx instead: the Ruby code
of the handler runs in a fiber, which yields to nginx and is resumed from
nginx’s event loop.
An access handler's code calls
Nginx::Async.sleep(500) in its fiber__sleep adds a timer of 500 ms to nginx's event loop, and Fiber.yield suspends the fiberThe handler returns
NGX_DONE: nginx keeps the request and leaves the handlerThe worker serves its other connections while the timer runs
The timer fires:
ngx_mrb_timer_handler marks the fiber ready to resume and posts the requestnginx calls the handler again, which resumes the fiber; when the code ends, the access phase handles its result as without the sleep
Nginx::Async.sleep, from the call until the handler's code goes on.Drawn from these lines of ngx_mruby at 819212d88 (2026-11-01):mrbgems/ngx_mruby_mrblib/mrblib/mrb_nginx.rblines 100 to 106src/http/ngx_http_mruby_async.clines 415 to 430, 503 to 591, 615 to 630 and 659 to 693src/http/ngx_http_mruby_module.clines 942 to 959 and 1099 to 1132src/http/ngx_http_mruby_core.hlines 30 to 35
- ngx_mruby runs the code of each handler in a fiber of mruby
(
ngx_mrb_start_fiber).Nginx::Async.sleeparms an nginx timer and yields the fiber; while it is suspended, the handler has returnedNGX_DONE, and the worker serves other connections. - When the timer fires,
ngx_mrb_timer_handlermarks the fiber ready to resume and posts the request, and nginx calls the handler again. The handler resumes the fiber instead of starting the code. When the code ends, the handler returns its result to the phase as a handler that did not wait does: an access handler without a result lets nginx go on with the next access handler, and a 403 undersatisfy anylets nginx try the next one. While the fiber waits, nginx does not run the code again. - An
mruby_sethandler runs inside the script of the rewrite module, so nginx does not call it again: ngx_mruby resumes its fiber, sets the variable when the code ends, and runs the phases from the next handler. Nginx::Async::HTTP.sub_requeststarts an nginx subrequest and yields. When the subrequest ends, nginx wakes the request, calls the handler again, and the handler resumes the fiber, to whichsub_requestreturns the response.mruby_setand the post-read, server rewrite, rewrite, access and content handlers can wait and resume. A suspended handler returnsNGX_DONE.- nginx keeps the request of a content handler while
Nginx::Async.sleepwaits, since the 2.7.3 changes, which 3.x includes. The response or the returned status of the code completes the request. Up to 2.7.2, the request ended at the sleep without a response. Since 3.0.0,Nginx.redirecttakes effect when the calling handler ends, so the handlers of its target can wait as well. - A content handler can wait for
Nginx::Async::HTTP.sub_request, also afterNginx::Async.sleep, since 3.0.0; 2.7.3 raisesRuntimeErrorthere. Inmruby_set,Nginx::Async::HTTP.sub_requestraisesRuntimeErrorsince 3.0.0, because nginx does not wait for a subrequest of the rewrite script; 2.x went on to the content phase without waiting for the variable. In header/body filters and the log handler, both async methods raiseRuntimeError. See the 2.7.3 behavior changes and Nginx::Async .#sleep Nginx::Stream::Async.sleepwaits in the same way in the code of a stream session (mruby_stream,mruby_stream_code): when the timer fires, nginx calls the handler of the access phase again, the handler resumes the fiber, and the session goes on by the result of the code. A session runs its code once: a datagram of a UDP session or bytes from the client of a TCP session that arrive during the wait do not start it again.- When the client closes the connection while the code waits, the code goes
on: nginx does not read from the client of an HTTP/1.x request while the
handlers run, or from the client of a stream session while its code
waits, and sees the close when it writes the response or after the code
resumes. When nginx ends the request or the session during the wait, for
example when
worker_shutdown_timeoutexpires in a worker that shuts down, the fiber is not resumed: the code after the wait, anensureclause included, does not run. On a reload, the old workers finish the waits in flight before they exit. - Code that waits in
sleepof mruby-sleep, a socket of mruby-socket, a file, a shell command or a Redis call blocks the worker for that time (Trust boundary).
Nginx::