on_thread_start naming and documentation is ambiguous

[Sven Riedel]

The on_thread_start callback added in 6.4.0 is ambiguous in its name:

• Does start refer to when a thread is newly created or when the thread starts processing again after regaining control?
• Does it execute the block in the context of the newly created thread, in the global context after the thread has been created but before it is executed, or in the global context before the thread is created? (after checking the relevant PR, it seems to be the last possibility, while I was expecting the first)

Unfortunately the documentation in dsl.rb is similarly ambiguous, unless you already know what is meant:

# Code to run immediately before a thread starts. The worker does not
# start new threads until this code finishes.

Refering to threads plural is odd here, suggesting to the reader that this callback is meant to be an user-supplied control instance on whether new threads are allowed to spawn or not. Maybe it is, but the naming would suggest to me for this to be something of an initialization/configuration callback. Maybe it isn't, since it seems like return values and exceptions don't seem to be considered in the subsequent spawning and executing of the new thread.

# This hook is useful for doing something when a thread
# starts.

This doesn't clarify what a thread start means, and in which context the block is being executed (see point of confusion #2 at the top). An example on what something useful can be may help here as well, to understand the motivation of the callbacks existance.

Maybe the following would be a bit less confusing (at least to me and only if I read the code and the intentions correctly, YMMV):

# Executes the block just before a new thread is spawned;
# the new thread will not be created until the control returns from the block.
# Return values are ignored and have no effect on the spawning and 
# execution of the new thread.

Renaming the block from on_thread_start to before_thread_creation would also help clear things up, but renaming it now that it is in a general release may be a bit messy :)

[Nate Berkopec]

Thanks for the feedback!