Appease the gods of stupid tests.

[perl5.git] / dist / threads / lib / threads.pm

diff --git a/dist/threads/lib/threads.pm b/dist/threads/lib/threads.pm
index 349beb1..0f6bca4 100644 (file)
--- a/dist/threads/lib/threads.pm
+++ b/dist/threads/lib/threads.pm
@@ -5,7 +5,7 @@ use 5.008;
 use strict;
 use warnings;
 
-our $VERSION = '1.81_01';
+our $VERSION = '2.04';
 my $XS_VERSION = $VERSION;
 $VERSION = eval $VERSION;
 
@@ -134,7 +134,17 @@ threads - Perl interpreter-based threads
 
 =head1 VERSION
 
-This document describes threads version 1.81
+This document describes threads version 2.02
+
+=head1 WARNING
+
+The "interpreter-based threads" provided by Perl are not the fast, lightweight
+system for multitasking that one might expect or hope for.  Threads are
+implemented in a way that make them easy to misuse.  Few people know how to
+use them correctly or will be able to provide help.
+
+The use of interpreter-based threads in perl is officially
+L<discouraged|perlpolicy/discouraged>.
 
 =head1 SYNOPSIS
 
@@ -424,11 +434,12 @@ C<$@> associated with the thread's execution status in its C<eval> context.
 
 =item $thr->_handle()
 
-This I<private> method returns the memory location of the internal thread
-structure associated with a threads object.  For Win32, this is a pointer to
-the C<HANDLE> value returned by C<CreateThread> (i.e., C<HANDLE *>); for other
-platforms, it is a pointer to the C<pthread_t> structure used in the
-C<pthread_create> call (i.e., C<pthread_t *>).
+This I<private> method returns a pointer (i.e., the memory location expressed
+as an unsigned integer) to the internal thread structure associated with a
+threads object.  For Win32, this is a pointer to the C<HANDLE> value returned
+by C<CreateThread> (i.e., C<HANDLE *>); for other platforms, it is a pointer
+to the C<pthread_t> structure used in the C<pthread_create> call (i.e.,
+C<pthread_t *>).
 
 This method is of no use for general Perl threads programming.  Its intent is
 to provide other (XS-based) thread modules with the capability to access, and
@@ -785,7 +796,7 @@ current operation has completed.  For instance, if the thread is I<stuck> on
 an I/O call, sending it a signal will not cause the I/O call to be interrupted
 such that the signal is acted up immediately.
 
-Sending a signal to a terminated thread is ignored.
+Sending a signal to a terminated/finished thread is ignored.
 
 =head1 WARNINGS
 
@@ -841,7 +852,7 @@ C<useithreads> configuration option.
 Having threads support requires all of Perl and all of the XS modules in the
 Perl installation to be rebuilt; it is not just a question of adding the
 L<threads> module (i.e., threaded and non-threaded Perls are binary
-incompatible.)
+incompatible).
 
 =item Cannot change stack size of an existing thread
 
@@ -939,6 +950,36 @@ For example:
 
 On MSWin32, each thread maintains its own set of environment variables.
 
+=item Catching signals
+
+Signals are I<caught> by the main thread (thread ID = 0) of a script.
+Therefore, setting up signal handlers in threads for purposes other than
+L</"THREAD SIGNALLING"> as documented above will not accomplish what is
+intended.
+
+This is especially true if trying to catch C<SIGALRM> in a thread.  To handle
+alarms in threads, set up a signal handler in the main thread, and then use
+L</"THREAD SIGNALLING"> to relay the signal to the thread:
+
+  # Create thread with a task that may time out
+  my $thr = threads->create(sub {
+      threads->yield();
+      eval {
+          $SIG{ALRM} = sub { die("Timeout\n"); };
+          alarm(10);
+          ...  # Do work here
+          alarm(0);
+      };
+      if ($@ =~ /Timeout/) {
+          warn("Task in thread timed out\n");
+      }
+  };
+
+  # Set signal handler to relay SIGALRM to thread
+  $SIG{ALRM} = sub { $thr->kill('ALRM') };
+
+  ... # Main thread continues working
+
 =item Parent-child threads
 
 On some platforms, it might not be possible to destroy I<parent> threads while
@@ -965,7 +1006,8 @@ signalling behavior is only in effect in the following situations:
 
 =item * Perl has been built with C<PERL_OLD_SIGNALS> (see C<perl -V>).
 
-=item * The environment variable C<PERL_SIGNALS> is set to C<unsafe> (see L<perlrun/"PERL_SIGNALS">).
+=item * The environment variable C<PERL_SIGNALS> is set to C<unsafe>
+(see L<perlrun/"PERL_SIGNALS">).
 
 =item * The module L<Perl::Unsafe::Signals> is used.
 
@@ -976,7 +1018,7 @@ the C<-E<gt>kill()> signalling method cannot be used.
 
 =item Returning closures from threads
 
-Returning closures from threads should not be relied upon.  Depending of the
+Returning closures from threads should not be relied upon.  Depending on the
 Perl version and the application code, results may range from success, to
 (apparently harmless) warnings of leaked scalar, or all the way up to crashing
 of the Perl interpreter.
@@ -1045,19 +1087,13 @@ Perl 5.8.0 or later
 L<threads> Discussion Forum on CPAN:
 L<http://www.cpanforum.com/dist/threads>
 
-Annotated POD for L<threads>:
-L<http://annocpan.org/~JDHEDDEN/threads-1.81/threads.pm>
-
-Source repository:
-L<http://code.google.com/p/threads-shared/>
-
 L<threads::shared>, L<perlthrtut>
 
 L<http://www.perl.com/pub/a/2002/06/11/threads.html> and
 L<http://www.perl.com/pub/a/2002/09/04/threads.html>
 
 Perl threads mailing list:
-L<http://lists.cpan.org/showlist.cgi?name=iThreads>
+L<http://lists.perl.org/list/ithreads.html>
 
 Stack size discussion:
 L<http://www.perlmonks.org/?node_id=532956>