Merge pull request #254 from catsby/cluster_docs

Starting point for documenting Clustered mode

README.md

@@ -73,6 +73,31 @@ Puma utilizes a dynamic thread pool which you can modify. You can set the minimu
 
 Puma will automatically scale the number of threads based on how much traffic is present. The current default is `0:16`. Feel free to experiment, but be careful not to set the number of maximum threads to a very large number, as you may exhaust resources on the system (or hit resource limits).
 
+### Clustered mode
+
+Puma 2 offers clustered mode, allowing you to use forked processes to handle multiple incoming requests concurrently, in addition to threads already provided. You can tune the number of workers with the `-w` (or `--workers`) flag:
+
+    $ puma -t 8:32 -w 3
+    
+On a ruby implementation that offers native threads, you should tune this number to match the number of cores available. 
+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 be 32 threads.
+
+Additionally, you can specify a block in your configuration that will be run on boot of each worker:
+
+    # config/puma.rb
+    on_worker_boot do
+      # configuration here
+    end
+
+This code can be used to setup the process before booting the application, allowing 
+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 to add hooks.
+
+Be sure to specify the location of your configuration file:
+
+    $ puma -t 8:32 -w 3 -C config/puma.rb
+
 ### Binding TCP / Sockets
 
 In contrast to many other server configs which require multiple flags, Puma simply uses one URI parameter with the `-b` (or `--bind`) flag:

lib/puma/cli.rb

@@ -694,7 +694,7 @@ module Puma
 
       begin
         Signal.trap "SIGTERM" do
-          # The worker installs there own SIGTERM when booted.
+          # The worker installs their own SIGTERM when booted.
           # Until then, this is run by the worker and the worker
           # should just exit if they get it.
           if Process.pid != master_pid