rubygems
/
puma
1
0
Fork 0
Code Packages Releases Activity

Explain WEB_CONCURRENCY and relation to preloading (#2874) 

This explains `WEB_CONCURRENCY` as an alternative to the `-w` flag, and
how `WEB_CONCURRENCY` can automatically enable preloading.

This also includes some minor edits to "Clustered mode" section for
improved flow and clarity.

[ci skip]
This commit is contained in:
Jonathan Hefner 2022-05-12 16:27:55 -05:00 committed by GitHub
parent 20df56b7ca
commit 914a0022cc
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 20 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
README.md
View File

@ -106,15 +106,23 @@ Puma also offers "clustered mode". Clustered mode `fork`s workers from a master
$ puma -t 8:32 -w 3
```
Or with the `WEB_CONCURRENCY` environment variable:
```
$ WEB_CONCURRENCY=3 puma -t 8:32
```
Note that threads are still used in clustered mode, and the `-t` thread flag setting is per worker, so `-w 2 -t 16:16` will spawn 32 threads in total, with 16 in each worker process.
In clustered mode, Puma can "preload" your application. This loads all the application code *prior* to forking. Preloading reduces total memory usage of your application via an operating system feature called [copy-on-write](https://en.wikipedia.org/wiki/Copy-on-write) (Ruby 2.0+ only). Use the `--preload` flag from the command line:
In clustered mode, Puma can "preload" your application. This loads all the application code *prior* to forking. Preloading reduces total memory usage of your application via an operating system feature called [copy-on-write](https://en.wikipedia.org/wiki/Copy-on-write).
If the `WEB_CONCURRENCY` environment variable is set to a value > 1 (and `--prune-bundler` has not been specified), preloading will be enabled by default. Otherwise, you can use the `--preload` flag from the command line:
```
$ puma -w 3 --preload
```
If you're using a configuration file, use the `preload_app!` method:
Or, if you're using a configuration file, you can use the `preload_app!` method:
```ruby
# config/puma.rb
@ -122,7 +130,9 @@ workers 3
preload_app!
```
Additionally, you can specify a block in your configuration file that will be run on boot of each worker:
Preloading can’t be used with phased restart, since phased restart kills and restarts workers one-by-one, and preloading copies the code of master into the workers.
When using clustered mode, you can specify a block in your configuration file that will be run on boot of each worker:
```ruby
# config/puma.rb
@ -135,12 +145,10 @@ This code can be used to setup the process before booting the application, allow
you to do some Puma-specific things that you don't want to embed in your application.
For instance, you could fire a log notification that a worker booted or send something to statsd. This can be called multiple times.
Constants loaded by your application (such as `Rails`) will not be available in `on_worker_boot`.
However, these constants _will_ be available if `preload_app!` is enabled, either explicitly in your `puma` config or automatically if
using 2 or more workers in cluster mode.
If `preload_app!` is not enabled and 1 worker is used, then `on_worker_boot` will fire, but your app will not be preloaded and constants will not be available.
Constants loaded by your application (such as `Rails`) will not be available in `on_worker_boot`
unless preloading is enabled.
`before_fork` specifies a block to be run before workers are forked:
You can also specify a block to be run before workers are forked, using `before_fork`:
```ruby
# config/puma.rb
@ -149,8 +157,6 @@ before_fork do
end
```
Preloading can’t be used with phased restart, since phased restart kills and restarts workers one-by-one, and `preload_app!` copies the code of master into the workers.
### Error handling
If puma encounters an error outside of the context of your application, it will respond with a 500 and a simple