In Rails 8.1, what do ActionDispatch::Executor and ActionDispatch::Reloader do for each request, and when must you wrap code yourself?
answer
- to_run and to_complete callbacks
- query cache, connections, Current reset
- completes when the body closes
- Reloader only when reloading
- Rails.application.executor.wrap in threads
basics
~20 sActionDispatch::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 linesclass 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
endgo deeper
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.
Explain the to_run and to_complete hooks, what they do by default, and why the Reloader middleware appears only when reloading is enabled.
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.
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.