ブロックせずに待つ
nginxのワーカーは、1つのイベントループで多くの接続を同時に処理します。sleepやソケットの読み込みのような、ブロックする呼び出しでハンドラが待つと、ワーカー全体が止まります。Nginx::Async.sleepとNginx::Async::HTTP.sub_requestを使うと、ハンドラはnginxを通して待ちます。ハンドラのRubyのコードはファイバーの中で動きます。このファイバーはnginxに制御を返し、nginxがイベントループからそのファイバーを再開します。
accessハンドラのコードが、ファイバーの中で呼ぶ
Nginx::Async.sleep(500)を__sleepがFiber.yieldがハンドラは返す。nginxはリクエストを保ったまま、ハンドラを離れる
NGX_DONEをタイマーが動いている間、ワーカーはほかの接続を処理する
タイマーが切れると、ファイバーを再開できる状態にして、リクエストをnginxに戻す
ngx_mrb_timer_handlerがnginxがハンドラをもう一度呼び、ハンドラがファイバーを再開する。コードが終わると、accessフェーズは待たなかったときと同じように結果を扱う
Nginx::Async.sleepを呼んでから、ハンドラのコードが先へ進むまでに起きることを示します。ngx_mrubyのソースの次の行から描きました。2026-11-01のコミット819212d88の行です。mrbgems/ngx_mruby_mrblib/mrblib/mrb_nginx.rbの100行から106行src/http/ngx_http_mruby_async.cの415行から430行、503行から591行、615行から630行、659行から693行src/http/ngx_http_mruby_module.cの942行から959行、1099行から1132行src/http/ngx_http_mruby_core.hの30行から35行
- ngx_mrubyは、
ngx_mrb_start_fiberで、各ハンドラのコードをmrubyのファイバーの中で実行します。Nginx::Async.sleepは、nginxのタイマーをセットしてファイバーを中断します。ファイバーが中断している間、ハンドラは既にNGX_DONEを返していて、ワーカーはほかの接続を処理します。 - タイマーが切れると、
ngx_mrb_timer_handlerはファイバーを再開できる状態にして、ngx_http_post_requestでリクエストをnginxに戻します。nginxはハンドラをもう一度呼び、ハンドラはコードを始めずにファイバーを再開します。コードが終わると、ハンドラは待たなかったハンドラと同じように結果をフェーズに返します。結果の無いaccessハンドラの後、nginxは次のaccessハンドラへ進みます。satisfy anyで403を返すと、nginxは次のaccessハンドラを試します。ファイバーが待っている間、nginxはコードをもう一度実行しません。 mruby_setのハンドラはrewriteモジュールのスクリプトの中で動くので、nginxはこのハンドラをもう一度呼びません。ngx_mrubyがファイバーを再開し、コードが終わると変数に値を入れ、次のハンドラからフェーズを進めます。Nginx::Async::HTTP.sub_requestは、nginxのサブリクエストを始めてファイバーを中断します。サブリクエストが終わると、nginxがリクエストを起こしてハンドラをもう一度呼び、ハンドラがファイバーを再開します。sub_requestは、そのファイバーにレスポンスを返します。mruby_setとpost-read、server rewrite、rewrite、access、contentのハンドラは待機して再開できます。中断したハンドラはNGX_DONEを返します。- 2.7.3の修正以降、nginxは
Nginx::Async.sleepで待つcontentハンドラのリクエストを保持します。3.xもこの修正を含みます。コードの応答や戻り値のステータスでリクエストが完了します。2.7.2までは、sleepの時点で応答せずにリクエストが終わりました。 - 3.0.0から、
Nginx.redirectは呼び出したハンドラが終わったときに効くので、リダイレクト先のハンドラも待てます。 - 3.0.0から、contentハンドラは
Nginx::Async.sleepの後でもNginx::Async::HTTP.sub_requestを待てます。2.7.3は、ここでRuntimeErrorを出します。 - 3.0.0から、
mruby_setではNginx::Async::HTTP.sub_requestがRuntimeErrorを出します。nginxは、rewriteモジュールのスクリプトのサブリクエストを待たないためです。2.xでは、nginxは変数を待たずにcontentフェーズへ進みました。 - ヘッダフィルタ、ボディフィルタ、logハンドラでは、両メソッドが
RuntimeErrorを起こします。 Nginx::Stream::Async.sleepも、streamのセッションのコード(mruby_stream、mruby_stream_code)で同じように待ちます。タイマーが切れると、nginxがaccessフェーズのハンドラをもう一度呼び、ハンドラがファイバーを再開します。セッションは、コードの結果に従って先へ進みます。セッションはコードを1回だけ実行します。待つ間に届いたUDPのセッションのデータグラムや、TCPのセッションのクライアントからのバイトで、コードがもう一度始まることはありません。- コードが待つ間にクライアントが接続を閉じても、コードは先へ進みます。nginxは、ハンドラが動く間はHTTP/1.xのリクエストのクライアントから読まず、コードが待つ間はstreamのセッションのクライアントからも読みません。閉じたことは、レスポンスを書くときか、コードの再開の後に分かります。待つ間にnginxがリクエストかセッションを終えると、ファイバーは再開しません。シャットダウン中のワーカーで
worker_shutdown_timeoutが切れたときがその例で、待ちの後のコードはensure節も含めて動きません。リロードでは、古いワーカーが処理中の待ちを最後まで進めてから終わります。 - mruby-sleepの
sleep、mruby-socketのソケット、ファイル、シェルのコマンド、Redisの呼び出しで待つコードは、その間ワーカーをブロックします。詳しくは信頼境界にあります。
リファレンスのNginx::
関連する制約の資料: