Skip to content

Puma plugin: add a forked_async mode, one forked process running the async supervisor - #839

Open
manuelmeurer wants to merge 1 commit into
rails:mainfrom
manuelmeurer:puma-plugin-forked-async
Open

manuelmeurer wants to merge 1 commit into
rails:mainfrom
manuelmeurer:puma-plugin-forked-async

Conversation

@manuelmeurer

Copy link
Copy Markdown

The problem

The Puma plugin has two ways of running Solid Queue:

  • fork (default): it forks the supervisor, which forks one process per worker, dispatcher and scheduler. With one dispatcher, two workers and a scheduler, that's six processes including Puma.
  • async: the supervisor and everything it supervises run as threads inside Puma's own process.

On small servers that run several apps, the memory of the forked processes adds up. Each of them shares memory with Puma at first, but even mostly idle ones end up with 40–150 MB of their own after a while. async avoids that, but it puts job threads next to request threads in one process. Jobs that use a lot of CPU then hold the GVL, and requests wait.

What's missing is the form in between: fork one process from Puma, and run the supervisor in async mode there. That's what bin/jobs --mode async already does next to a separate web server. This PR lets the plugin do it too.

Measured

Two Rails 8.1 apps on Ruby 4.0 with jemalloc, in a container limited to 2 CPUs. Each app calls Process.warmup before the first fork. Configuration: one dispatcher, two workers (3 threads and 1 thread), one scheduler, 3 Puma threads. Medians of 3 runs. "After load" means after 200 requests and 300 small jobs. Memory is the container's anonymous memory in MB.

fork forked_async async
Large app: after start 471 403 347
Large app: after 2 idle minutes 531 438 358
Large app: after load 652 495 385
Small app: after start 302 247 205
Small app: after 2 idle minutes 359 266 215
Small app: after load 446 324 251

Web latency (p50 / p95 in ms, 10 requests per second) while the workers ran a backlog of CPU-heavy jobs (150 ms of Ruby each):

fork forked_async async
Large app, /up 7.4 / 9.2 7.3 / 9.5 10,652 / 20,155
Large app, a page rendering 300 rows 59 / 73 59 / 71 9,989 / 19,698
Small app, /up 5.6 / 7.1 5.6 / 7.2 7,855 / 15,620

With jobs that mostly wait (sleeps standing in for API calls), all three looked alike: p95 of /up 7–9 ms, 13–17 ms with async.

Stopping Puma with TERM while three jobs ran, each needing a few seconds to finish (shutdown timeout 30 s):

So forked_async keeps most of the memory saving of async and the request latency of fork.

Why not just async

Running jobs in the web process works well when jobs mostly wait on I/O. It doesn't when some jobs do real work in Ruby: PDF rendering, imports, large JSON. Requests then wait behind them for seconds, as the numbers above show. async also ties a job's crash or memory growth to the web process. forked_async keeps both in a separate process, at the cost of one process instead of one per supervised process.

What this changes

  • solid_queue_mode :forked_async makes the plugin fork once, as in fork mode, and start the supervisor with mode: :async in that child.
  • Everything else is the same as fork:
    • the child stops itself when Puma goes away;
    • the plugin stops Puma when the child exits;
    • it stops the child before Puma stops or restarts.
  • The supervisor is standalone in the child, so it handles TERM, INT and QUIT itself. It runs the graceful termination that bin/jobs --mode async runs.
  • The processes configuration option is ignored, as in async.
  • Tests: a new plugin test with the existing shared plugin tests (jobs run, restart on USR2), plus:
    • a single process holds all registrations;
    • Puma stops when that process is killed;
    • an in-flight job finishes and is recorded as finished on stop.
  • README: a paragraph under "Running as a fork or asynchronously".

About the name: the plugin's mode says where the supervisor runs, while the supervisor's own mode says whether it forks or uses threads. This is the async supervisor, forked from Puma, hence forked_async. I'm happy to change it if you prefer another name.

`solid_queue_mode :forked_async` forks one process from Puma, as in
`fork` mode, and runs the supervisor with `mode: :async` there, so all
workers, dispatchers and the scheduler are threads of that one process.
Copilot AI balanced review requested due to automatic review settings November 19, 2026 18:19

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The forked_async addition has no active review issues blocking approval.

No open issues 🎉

What changed in this PR

Adds solid_queue_mode :forked_async to the Puma plugin, providing a middle ground between fully forked and in-process async execution. It runs Solid Queue’s supervisor and worker threads in one child process, reducing process overhead while keeping jobs separate from web requests.

Changes:

  • Reuses the forked lifecycle with an async supervisor in the child.
  • Adds integration coverage for shared process registration, supervisor failure, and graceful job completion during shutdown.
  • Documents the new mode and its isolation and configuration tradeoffs.
File Description
test/​integration/​puma/​plugin_forked_async_test.rb Adds lifecycle and shutdown tests for the new mode.
test/​dummy/​config/​puma_forked_async.rb Configures the test app to use forked_async.
README.md Explains usage, process layout, and tradeoffs.
lib/​puma/​plugin/​solid_queue.rb Routes the new mode through forked startup with an async supervisor.

Review effort: Balanced

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants