skip to content

In Rails 8.1, what do ActionDispatch::Executor and ActionDispatch::Reloader do for each request, and when must you wrap code yourself?

level: seniorimportance: should knowfreq 30%

answer

  1. to_run and to_complete callbacks
  2. query cache, connections, Current reset
  3. completes when the body closes
  4. Reloader only when reloading
  5. Rails.application.executor.wrap in threads

basics

~20 s

ActionDispatch::Executor wraps every request in the app's executor, whose callbacks enable the query cache, release database connections and reset Current attributes. ActionDispatch::Reloader, present only when reloading is on, reloads changed code first. Threads you start need Rails.application.executor.wrap.

solid answer

~40 s

`ActionDispatch::Executor` calls `Rails.application.executor.run!` before the request and `complete!` after it. Its `to_run` and `to_complete` hooks turn the Active Record query cache on and off, return the thread's leased connection to the pool when no transaction is open, clear `ActiveSupport::CurrentAttributes` and, in development, hold the reloading interlock. Completion happens when the server closes the response body, or, new in 8.1, on `rack.response_finished` when the server supports it. `ActionDispatch::Reloader` is in the stack only when reloading is enabled; it checks for changed files, unloads and reloads autoloaded code before the request and runs `to_prepare` callbacks. Rails wraps requests and Active Job itself, but a `Thread.new` or a thread pool you start must wrap its body in `Rails.application.executor.wrap`. A long-running top-level loop of your own uses `Rails.application.reloader.wrap` per unit of work instead.

code

ruby · 13 lines
ruby
class ParcelsController < ApplicationController
  def refresh
    parcel_ids = params.expect(parcel_ids: [])

    Thread.new do
      Rails.application.executor.wrap do
        Parcel.where(id: parcel_ids).find_each(&:refresh_carrier_status!)
      end
    end

    head :accepted
  end
end

go deeper

for a junior

Recall that Rails wraps each request so that database connections and Current attributes are cleaned up afterwards, and that development reloads changed code between requests.

for a middle

Explain the to_run and to_complete hooks, what they do by default, and why the Reloader middleware appears only when reloading is enabled.

for a senior

Diagnose leaked connections, Current values bleeding across work, and reload deadlocks by checking whether spawned threads and custom loops use executor.wrap or reloader.wrap.

for a principal

Set a team rule for concurrency inside the app: when spawning threads is acceptable at all, and that every framework-level entry point you add must wrap its work.

## Two wrappers around application code Rails separates **framework code** (the server loop, the job runner) from **application code** (your controllers, models and jobs). Whenever the framework calls into application code, it wraps the call in a unit of work so that per-unit state is set up and torn down reliably. Two objects provide that wrapper, and each has a Rack middleware that applies it to requests: - **`Rails.application.executor`**, a subclass of `ActiveSupport::Executor`, applied by `ActionDispatch::Executor`; - **`Rails.application.reloader`**, a subclass of `ActiveSupport::Reloader`, applied by `ActionDispatch::Reloader`. ## What the Executor does per request `ActionDispatch::Executor` calls `run!` on the executor before passing the request on, which fires its **`to_run`** callbacks, and `complete!` at the end, which fires **`to_complete`**. In a default app those hooks: - enable the Active Record **query cache** on each connection pool and disable and clear it at completion; - **return the leased database connection** to its pool at completion, unless a transaction on it is still open; - clear **`ActiveSupport::CurrentAttributes`**, so `Current.user` from one request never appears in the next; - push and pop the execution context used for error-reporting context; - in development, register the thread as running in the **reloading interlock**, so a reload waits until no thread is mid-request. Two details matter in production: 1. Completion is tied to the **response body**, not to the action returning. The middleware wraps the body in a `Rack::BodyProxy` and completes when the server closes it, so a streamed body keeps its connection until streaming ends. In Rails 8.1, when the server provides `rack.response_finished`, completion is deferred to that callback instead, after the response is written. 2. The middleware reports an exception that escapes the stack to the Rails error reporter with `handled: false` before re-raising it. ## What the Reloader does `ActionDispatch::Reloader` is added only when reloading is enabled, which the generated development environment does with `config.enable_reloading = true`. For each request it asks the reloader whether anything changed; with `config.reload_classes_only_on_change` (the default) a file watcher answers. If something did: 1. it waits, through the interlock, until no other thread is running application code; 2. it unloads autoloaded constants, firing `before_class_unload` and `after_class_unload`; 3. it runs the `to_prepare` callbacks again, so code that configures reloadable classes re-runs against the new ones. If nothing changed, it adds no callbacks at all. In production the middleware is absent and the reloader is only a pass-through to the executor. | | `ActionDispatch::Executor` | `ActionDispatch::Reloader` | |---|---|---| | In the default stack | always | only when reloading is enabled | | Wraps with | `Rails.application.executor` | `Rails.application.reloader` | | Core job | per-unit setup and cleanup | reload changed code before the unit | | Use it yourself for | threads you spawn | long-running top-level loops | ## When you must wrap code yourself Rails wraps the entry points it owns: requests (both middleware), Active Job executions (the reloader) and Action Cable message handlers (the executor). Code that starts **its own threads or loops** is outside those wrappers: - A `Thread.new` or a `Concurrent::Promises` future started from a request runs on a different thread; the request's executor does not cover it. Wrap the body in `Rails.application.executor.wrap { ... }`. Without it, a connection the thread leases may stay checked out, so busy pools hit `ActiveRecord::ConnectionTimeoutError`, `Current` values are never reset, and in development a reload can run while that thread is still using the old classes. - A long-running top-level process of your own, such as a custom queue consumer, should call `Rails.application.reloader.wrap { ... }` around each unit of work, so it picks up changed code in development and gets executor cleanup everywhere. - Child threads must use the executor, never the reloader: a reload started in a child would wait for the parent, which is itself waiting for the child, which deadlocks. `wrap` is re-entrant: if the executor is already active on the current thread, it simply yields. ## Symptoms that point here - `ActiveRecord::ConnectionTimeoutError` under load while the database itself is idle: look for threads or loops that lease connections outside an executor. - A `Current` value from one unit of work showing up in another: the code that set it ran without a wrap, so nothing cleared it. - In development, failures that appear only right after an edit, such as an object no longer passing `is_a?(Parcel)`: an unwrapped thread was still running when the reload replaced the class, because the interlock did not know about it.

  • In Rails 8.1, why does a streamed response keep its database connection until streaming ends?
    `ActionDispatch::Executor` completes the unit of work when the server closes the response body, through a `Rack::BodyProxy`, or on `rack.response_finished` when the server provides it. Until then the `to_complete` hooks, including the one that returns the leased connection, have not run.
  • In a Rails app, why should a thread spawned inside a request call the executor rather than the reloader?
    A reload must wait until no thread is running application code. If a child thread triggered one while its parent request was waiting on that child, the reload would wait for the parent and the parent for the child: a deadlock. The executor never reloads, so it is safe in child threads.
  • In Rails 8.1, where do the Executor and the Reloader sit in the default middleware stack?
    `ActionDispatch::Executor` sits near the top, below `ActionDispatch::Static`, so almost everything else runs inside the unit of work. `ActionDispatch::Reloader`, when present, sits lower, below the exception middleware and above `ActionDispatch::Callbacks`, so reload errors are rendered by `ActionDispatch::DebugExceptions`.

The Executor is a hotel's check-in and check-out desk: every guest is handed a room key on arrival and the room is cleaned and the key returned at departure, whether the stay was short or long. Guests who sneak in through a side door (unwrapped threads) skip both, so their rooms are never cleaned.

  • ActionDispatch::Executor exists only to reload code in development.
  • ActionDispatch::Reloader reloads changed code on every production request.
  • A Thread.new started in a controller inherits the request's executor wrap.
  • The executor completes as soon as the controller action returns.
  • ActionDispatch::Callbacks returns database connections to the pool after each request.

Assumes Rails 8.1; ActionDispatch::Executor defers completion to rack.response_finished, when the server provides it, since 8.1.0.