Better document the hooks. Fixes #840

examples/config.rb

@@ -110,31 +110,46 @@
 #
 # workers 2
 
-# Code to run when a worker boots to setup the process before booting
-# the app.
+# Code to run immediately before the masters starts workers.
 #
-# This can be called multiple times to add hooks.
+# before_fork do
+#   puts "Starting workers..."
+# end
+
+# Code to run in a worker before it starts serving requests.
+#
+# This is called everytime a worker is to be started.
 #
 # on_worker_boot do
 #   puts 'On worker boot...'
 # end
 
-# Code to run when a worker boots to setup the process after booting
-# the app.
-#
-# This can be called multiple times to add hooks.
-#
-# after_worker_boot do
-#   puts 'After worker boot...'
-# end
-
-# Code to run when a worker shutdown.
+# Code to run in a worker right before it exits.
 #
+# This is called everytime a worker is to be started.
 #
 # on_worker_shutdown do
 #   puts 'On worker shutdown...'
 # end
 
+# Code to run in the master right before a worker is started. The worker's
+# index is passed as an argument.
+#
+# This is called everytime a worker is to be started.
+#
+# on_worker_fork do
+#   puts 'Before worker fork...'
+# end
+
+# Code to run in the master after a worker has been started. The worker's
+# index is passed an an argument.
+#
+# This is called everytime a worker is to be started.
+#
+# after_worker_fork do
+#   puts 'After worker fork...'
+# end
+
 # Allow workers to reload bundler context when master process is issued
 # a USR1 signal. This allows proper reloading of gems while the master
 # is preserved across a phased-restart. (incompatible with preload_app)

lib/puma/dsl.rb

@@ -291,6 +291,15 @@ module Puma
       _ary(:before_fork) << block
     end
 
+    # *Cluster mode only* Code to run in a worker when it boots to setup
+    # the process before booting the app.
+    #
+    # This can be called multiple times to add hooks.
+    #
+    def on_worker_boot(&block)
+      _ary(:before_worker_boot) << block
+    end
+
     # *Cluster mode only* Code to run immediately before a worker shuts
     # down (after it has finished processing HTTP requests). These hooks
     # can block if necessary to wait for background operations unknown
@@ -302,16 +311,7 @@ module Puma
       _ary(:before_worker_shutdown) << block
     end
 
-    # *Cluster mode only* Code to run when a worker boots to setup
-    # the process before booting the app.
-    #
-    # This can be called multiple times to add hooks.
-    #
-    def on_worker_boot(&block)
-      _ary(:before_worker_boot) << block
-    end
-
-    # *Cluster mode only* Code to run when a master process is
+    # *Cluster mode only* Code to run in the master when it is
     # about to create the worker by forking itself.
     #
     # This can be called multiple times to add hooks.
@@ -320,15 +320,17 @@ module Puma
       _ary(:before_worker_fork) << block
     end
 
-    # *Cluster mode only* Code to run when a worker boots to setup
-    # the process after booting the app.
+    # *Cluster mode only* Code to run in the master after it starts
+    # a worker.
     #
     # This can be called multiple times to add hooks.
     #
-    def after_worker_boot(&block)
+    def after_worker_fork(&block)
       _ary(:after_worker_fork) << block
     end
 
+    alias_method :after_worker_boot, :after_worker_fork
+
     # The directory to operate out of.
     def directory(dir)
       @options[:directory] = dir.to_s