Expand documentation for on_thread_start and on_thread_exit. Close #3229

lib/puma/dsl.rb

@@ -729,11 +729,15 @@ def on_refork(key = nil, &block)
       process_hook :before_refork, key, block, 'on_refork'
     end
 
-    # Code to run immediately before a thread starts. The worker does not
-    # start new threads until this code finishes.
+    # Provide a block to be executed just before a thread is added to the thread
+    # pool. Be careful: while the block executes, thread creation is delayed, and 
+    # probably a request will have to wait too! The new thread will not be added to 
+    # the threadpool until the provided block returns. 
     #
-    # This hook is useful for doing something when a thread
-    # starts.
+    # Return values are ignored. 
+    # Raising an exception will log a warning.
+    # 
+    # This hook is useful for doing something when the thread pool grows.
     #
     # This can be called multiple times to add several hooks.
     #
@@ -746,8 +750,15 @@ def on_thread_start(&block)
       @options[:before_thread_start] << block
     end
 
-    # Code to run immediately before a thread exits. The worker does not
-    # accept new requests until this code finishes.
+    # Provide a block to be executed after a thread is trimmed from the thread 
+    # pool. Be careful: while this block executes, Puma's main loop is 
+    # blocked, so no new requests will be picked up.
+    # 
+    # This hook only runs when a thread in the threadpool is trimmed by Puma. 
+    # It does not run when a thread dies due to exceptions or any other cause.
+    #
+    # Return values are ignored. 
+    # Raising an exception will log a warning.
     #
     # This hook is useful for cleaning up thread local resources when a thread
     # is trimmed.