Add a section on how to submit a patch

[p5sagit/p5-mst-13.2.git] / pod / perlthrtut.pod

diff --git a/pod/perlthrtut.pod b/pod/perlthrtut.pod
index a6b0b18..e1acf6d 100644 (file)
--- a/pod/perlthrtut.pod
+++ b/pod/perlthrtut.pod
@@ -10,9 +10,9 @@ model, each thread runs in its own Perl interpreter, and any data sharing
 between threads must be explicit.  The user-level interface for I<ithreads>
 uses the L<threads> class.
 
-B<NOTE>: There is another older Perl threading flavor called the 5.005 model
-that used the L<Threads> class.  This old model is known to have problems, is
-deprecated, and support for it will be removed in release 5.10.  You are
+B<NOTE>: There was another older Perl threading flavor called the 5.005 model
+that used the L<Threads> class.  This old model was known to have problems, is
+deprecated, and was removed for release 5.10.  You are
 strongly encouraged to migrate any existing 5.005 threads code to the new
 model as soon as possible.
 
@@ -323,6 +323,36 @@ detach itself:
         # Do more work
     }
 
+=head2 Process and Thread Termination
+
+With threads one must be careful to make sure they all have a chance to
+run to completion, assuming that is what you want.
+
+An action that terminates a process will terminate I<all> running
+threads.  die() and exit() have this property,
+and perl does an exit when the main thread exits,
+perhaps implicitly by falling off the end of your code,
+even if that's not what you want.
+
+As an example of this case, this code prints the message
+"Perl exited with active threads: 2 running and unjoined":
+
+    use threads;
+    my $thr1 = threads->new(\&thrsub, "test1");
+    my $thr2 = threads->new(\&thrsub, "test2");
+    sub thrsub {
+       my ($message) = @_;
+       sleep 1;
+       print "thread $message\n";
+    }
+
+But when the following lines are added at the end:
+
+    $thr1->join;
+    $thr2->join;
+
+it prints two lines of output, a perhaps more useful outcome.
+
 =head1 Threads And Data
 
 Now that we've covered the basics of threads, it's time for our next
@@ -596,7 +626,6 @@ this:
 
     $DataQueue->enqueue(12);
     $DataQueue->enqueue("A", "B", "C");
-    $DataQueue->enqueue(\$thr);
     sleep(10);
     $DataQueue->enqueue(undef);
     $thr->join();