Feature #15909: Improve Thread#exit documentation

• Status: Open
• Priority: Normal
• Assignee: -
• Target version: -

[womble (Matt Palmer)]

Whilst writing some low-level threading code, I came across a couple of unexpected (though useful) behaviours of Thread#exit (aka #kill, #terminate) that I think are worth documenting for the benefit of future generations. Attached is my attempt to write that documentation. Further, I found what I think are some inaccuracies in the existing documentation for Thread#exit, so I attempted to fix those, too.

Detailed rationale for each change, in order of their appearance in the patch:

• As far as I can see, all return calls return thread, and thread is never mutated, so I can't see a way nil could ever be returned.
• The thread is not actually terminated by this method; instead, it is merely marked to be terminated.
• I can't find anywhere in the call tree that pokes the thread scheduler to run another thread.
• ensure blocks being run, rather than the thread just immediately up and dying, was the first unexpected behaviour I came across.
• Being able to defer termination via .handle_interrupt was the second unexpected behaviour I found.