X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlthrtut.pod;h=e1acf6d1901d158a5b2d0e33c3291555380e95ae;hb=c2cf2042fe2e21eb73dcdef54aa1b0e379ae413d;hp=c0ad9158bbcf8212d784a3b97d2d6af5fb857a71;hpb=c3e59998489df5fb30c82b6a5cc3359f27348c64;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlthrtut.pod b/pod/perlthrtut.pod
index c0ad915..e1acf6d 100644
--- 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.
 
@@ -117,7 +117,7 @@ step back a bit and think about what you want to do and how Perl can
 do it.
 
 However, it is important to remember that Perl threads cannot magically
-do things unless your operating system's threads allows it. So if your
+do things unless your operating system's threads allow it. So if your
 system blocks the entire process on C<sleep()>, Perl usually will, as well.
 
 B<Perl Threads Are Different.>
@@ -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();
@@ -621,7 +650,7 @@ threads to have the I<lock> at any one time.
 =head2 Basic semaphores
 
 Semaphores have two methods, C<down()> and C<up()>: C<down()> decrements the resource
-count, while up() increments it. Calls to C<down()> will block if the
+count, while C<up()> increments it. Calls to C<down()> will block if the
 semaphore's current count would decrement below zero.  This program
 gives a quick demonstration:
 
@@ -690,8 +719,8 @@ of these defaults simply by passing in different values:
 If C<down()> attempts to decrement the counter below zero, it blocks until
 the counter is large enough.  Note that while a semaphore can be created
 with a starting count of zero, any C<up()> or C<down()> always changes the
-counter by at least one, and so C<$semaphore->down(0)> is the same as
-C<$semaphore->down(1)>.
+counter by at least one, and so C<< $semaphore->down(0) >> is the same as
+C<< $semaphore->down(1) >>.
 
 The question, of course, is why would you do something like this? Why
 create a semaphore with a starting count that's not one, or why
@@ -718,9 +747,10 @@ threads quietly block and unblock themselves.
 Larger increments or decrements are handy in those cases where a
 thread needs to check out or return a number of resources at once.
 
-=head2 cond_wait() and cond_signal()
+=head2 Waiting for a Condition
 
-These two functions can be used in conjunction with locks to notify
+The functions C<cond_wait()> and C<cond_signal()>
+can be used in conjunction with locks to notify
 co-operating threads that a resource has become available. They are
 very similar in use to the functions found in C<pthreads>. However
 for most purposes, queues are simpler to use and more intuitive. See
@@ -778,7 +808,7 @@ C<tid()> is a thread object method that returns the thread ID of the
 thread the object represents.  Thread IDs are integers, with the main
 thread in a program being 0.  Currently Perl assigns a unique TID to
 every thread ever created in your program, assigning the first thread
-to be created a tid of 1, and increasing the tid by 1 for each new
+to be created a TID of 1, and increasing the TID by 1 for each new
 thread that's created.  When used as a class method, C<threads-E<gt>tid()>
 can be used by a thread to get its own TID.
 
@@ -1020,7 +1050,9 @@ threads.  See L<threads/"THREAD SIGNALLING> for more details.)
 
 Whether various library calls are thread-safe is outside the control
 of Perl.  Calls often suffering from not being thread-safe include:
-C<localtime()>, C<gmtime()>, C<get{gr,host,net,proto,serv,pw}*()>, C<readdir()>,
+C<localtime()>, C<gmtime()>,  functions fetching user, group and
+network information (such as C<getgrent()>, C<gethostent()>,
+C<getnetent()> and so on), C<readdir()>,
 C<rand()>, and C<srand()> -- in general, calls that depend on some global
 external state.