Document the effect of thread creation context.

p4raw-id: //depot/perl@19236

1 files changed, 7 insertions, 0 deletions

diff --git a/ext/threads/threads.pm b/ext/threads/threads.pm
index 337aaf5027..6e2f0efd31 100755
--- a/ext/threads/threads.pm
+++ b/ext/threads/threads.pm
@@ -151,11 +151,18 @@ object. The new() method is an alias for create().
 This will wait for the corresponding thread to join. When the thread
 finishes, join() will return the return values of the entry point
 function. If the thread has been detached, an error will be thrown.
+
+The context (scalar or list) of the thread creation is also the
+context for join().  This means that if you intend to return an array
+from a thread, you must use C<my ($thread) = threads->new(...)>, and
+that if you intend to return a scalar, you must use C<my $thread = ...>.
+
 If the program exits without all other threads having been either
 joined or detached, then a warning will be issued. (A program exits
 either because one of its threads explicitly calls exit(), or in the
 case of the main thread, reaches the end of the main program file.)
 
+
 =item $thread->detach
 
 Will make the thread unjoinable, and cause any eventual return value