コンテンツにスキップ

ブロックせずに待つ

nginxのワーカーは、1つのイベントループで多くの接続を同時に処理します。sleepやソケットの読み込みのような、ブロックする呼び出しでハンドラが待つと、ワーカー全体が止まります。Nginx::Async.sleepとNginx::Async::HTTP.sub_requestを使うと、ハンドラはnginxを通して待ちます。ハンドラのRubyのコードはファイバーの中で動きます。このファイバーはnginxに制御を返し、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::Asyncに、両方のメソッドの説明があります。ngx_mrubyがハンドラのファイバーをどう保ち、再開し、取り消すかは、開発者向けのハンドラが待つ仕組みに書いてあります。

関連する制約の資料: