From 7a0e0c27639f48d53da07cab4c5a4262b96ecc3c Mon Sep 17 00:00:00 2001 From: Nate Berkopec Date: Fri, 22 Sep 2023 15:47:48 +0900 Subject: [PATCH] Expand documentation for on_thread_start and on_thread_exit. Close #3229 --- lib/puma/dsl.rb | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/lib/puma/dsl.rb b/lib/puma/dsl.rb index 5139e661d3..4797e9383f 100644 --- a/lib/puma/dsl.rb +++ b/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.