Repository navigation
Puma plugin: add a forked_async mode, one forked process running the async supervisor - #839
Open
manuelmeurer wants to merge 1 commit into
Open
manuelmeurer wants to merge 1 commit into
manuelmeurer wants to merge 1 commit into
Conversation
`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.
There was a problem hiding this comment.
🟢 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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
asyncavoids 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
asyncmode there. That's whatbin/jobs --mode asyncalready 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.warmupbefore 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.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):
/up/upWith jobs that mostly wait (sleeps standing in for API calls), all three looked alike: p95 of
/up7–9 ms, 13–17 ms withasync.Stopping Puma with TERM while three jobs ran, each needing a few seconds to finish (shutdown timeout 30 s):
forkandforked_asynclet all three finish and record them as finished, every time.asynclet them finish, but in all 8 tries the jobs ended up back in the queue, to run again. See Puma plugin in async mode: jobs that finish while Puma stops go back to the queue #838.So
forked_asynckeeps most of the memory saving ofasyncand the request latency offork.Why not just
asyncRunning 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.
asyncalso ties a job's crash or memory growth to the web process.forked_asynckeeps both in a separate process, at the cost of one process instead of one per supervised process.What this changes
solid_queue_mode :forked_asyncmakes the plugin fork once, as inforkmode, and start the supervisor withmode: :asyncin that child.fork:bin/jobs --mode asyncruns.processesconfiguration option is ignored, as inasync.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.