From: Rafael Garcia-Suarez Date: Tue, 6 Feb 2007 22:37:34 +0000 (+0000) Subject: Upgrade to threads.pm 1.59 (doc tweaks) X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=5cbb7319c02768b8f1a4ff061db4d0296d58bf4d;p=p5sagit%2Fp5-mst-13.2.git Upgrade to threads.pm 1.59 (doc tweaks) p4raw-id: //depot/perl@30152 --- diff --git a/ext/threads/Changes b/ext/threads/Changes index 6eec369..a9ba0b3 100755 --- a/ext/threads/Changes +++ b/ext/threads/Changes @@ -1,5 +1,8 @@ Revision history for Perl extension threads. +1.59 - Mon Feb 5 16:05:44 EST 2007 + - POD tweaks per Wolfgang Laun + 1.58 Wed Jan 24 13:15:34 EST 2007 - Fix race conditions on thread destruction (Dave Mitchell) - Ignore thread return value(s) in void context diff --git a/ext/threads/README b/ext/threads/README index 0194702..149247e 100755 --- a/ext/threads/README +++ b/ext/threads/README @@ -1,4 +1,4 @@ -threads version 1.58 +threads version 1.59 ==================== This module exposes interpreter threads to the Perl level. diff --git a/ext/threads/t/exit.t b/ext/threads/t/exit.t index a85c411..7f5e21b 100644 --- a/ext/threads/t/exit.t +++ b/ext/threads/t/exit.t @@ -56,7 +56,7 @@ my $rc = $thr->join(); ok(! defined($rc), 'Exited: threads->exit()'); -run_perl(prog => 'use threads 1.58;' . +run_perl(prog => 'use threads 1.59;' . 'threads->exit(86);' . 'exit(99);', nolib => ($ENV{PERL_CORE}) ? 0 : 1, @@ -104,7 +104,7 @@ $rc = $thr->join(); ok(! defined($rc), 'Exited: $thr->set_thread_exit_only'); -run_perl(prog => 'use threads 1.58 qw(exit thread_only);' . +run_perl(prog => 'use threads 1.59 qw(exit thread_only);' . 'threads->create(sub { exit(99); })->join();' . 'exit(86);', nolib => ($ENV{PERL_CORE}) ? 0 : 1, @@ -112,7 +112,7 @@ run_perl(prog => 'use threads 1.58 qw(exit thread_only);' . is($?>>8, 86, "'use threads 'exit' => 'thread_only'"); -my $out = run_perl(prog => 'use threads 1.58;' . +my $out = run_perl(prog => 'use threads 1.59;' . 'threads->create(sub {' . ' exit(99);' . '});' . @@ -125,7 +125,7 @@ is($?>>8, 99, "exit(status) in thread"); like($out, '1 finished and unjoined', "exit(status) in thread"); -$out = run_perl(prog => 'use threads 1.58 qw(exit thread_only);' . +$out = run_perl(prog => 'use threads 1.59 qw(exit thread_only);' . 'threads->create(sub {' . ' threads->set_thread_exit_only(0);' . ' exit(99);' . @@ -139,7 +139,7 @@ is($?>>8, 99, "set_thread_exit_only(0)"); like($out, '1 finished and unjoined', "set_thread_exit_only(0)"); -run_perl(prog => 'use threads 1.58;' . +run_perl(prog => 'use threads 1.59;' . 'threads->create(sub {' . ' $SIG{__WARN__} = sub { exit(99); };' . ' die();' . diff --git a/ext/threads/t/thread.t b/ext/threads/t/thread.t index 6020807..4bc45a8 100644 --- a/ext/threads/t/thread.t +++ b/ext/threads/t/thread.t @@ -171,7 +171,7 @@ package main; # bugid #24165 -run_perl(prog => 'use threads 1.58;' . +run_perl(prog => 'use threads 1.59;' . 'sub a{threads->create(shift)} $t = a sub{};' . '$t->tid; $t->join; $t->tid', nolib => ($ENV{PERL_CORE}) ? 0 : 1, diff --git a/ext/threads/threads.pm b/ext/threads/threads.pm index e487f3b..e0c000d 100755 --- a/ext/threads/threads.pm +++ b/ext/threads/threads.pm @@ -5,7 +5,7 @@ use 5.008; use strict; use warnings; -our $VERSION = '1.58'; +our $VERSION = '1.59'; my $XS_VERSION = $VERSION; $VERSION = eval $VERSION; @@ -138,7 +138,7 @@ threads - Perl interpreter-based threads =head1 VERSION -This document describes threads version 1.58 +This document describes threads version 1.59 =head1 SYNOPSIS @@ -406,7 +406,7 @@ to the more natural forms: C creates a thread to execute the block immediately following it. This block is treated as an anonymous subroutine, and so must have a -semi-colon after the closing brace. Like Ccreate()>, C +semicolon after the closing brace. Like Ccreate()>, C returns a I object. =item $thr->error() @@ -476,7 +476,7 @@ If C really is needed, then consider using the following: threads->exit() if threads->can('exit'); # Thread friendly exit(status); -=item use threads 'exit' => 'thread_only' +=item use threads 'exit' => 'threads_only' This globally overrides the default behavior of calling C inside a thread, and effectively causes such calls to behave the same as @@ -496,16 +496,15 @@ thread only. =item $thr->set_thread_exit_only(boolean) This can be used to change the I behavior for a thread after -it has been created. With a I argument, C will cause the only -the thread to exit. With a I argument, C will terminate the +it has been created. With a I argument, C will cause only the +thread to exit. With a I argument, C will terminate the application. The I
thread is unaffected by this call. =item threads->set_thread_exit_only(boolean) -Class method for use inside a thread to changes its own behavior for -C. +Class method for use inside a thread to change its own behavior for C. The I
thread is unaffected by this call. @@ -521,13 +520,13 @@ thread. =item $thr->is_running() Returns true if a thread is still running (i.e., if its entry point function -has not yet finished/exited). +has not yet finished or exited). =item $thr->is_joinable() Returns true if the thread has finished running, is not detached and has not -yet been joined. In other works, the thread is ready to be joined and will -not I. +yet been joined. In other words, the thread is ready to be joined, and a call +to C<$thr-Ejoin()> will not I. =item $thr->is_detached() @@ -552,7 +551,7 @@ the appropriate type to be returned from C<-Ejoin()>. Because thread creation and thread joining may occur in different contexts, it may be desirable to state the context explicitly to the thread's entry point -function. This may be done by calling C<-Ecreate()> with a parameter hash +function. This may be done by calling C<-Ecreate()> with a hash reference as the first argument: my $thr = threads->create({'context' => 'list'}, \&foo); @@ -569,7 +568,7 @@ returning a value (i.e., I context), you would do the following: ... $thr->join(); -The context type may also be used as the I in the parameter hash followed +The context type may also be used as the I in the hash reference followed by a I value: threads->create({'scalar' => 1}, \&foo); @@ -598,8 +597,9 @@ L. =head2 threads->wantarray() -Class method to return the current thread's context. This is the same as -running L in the current thread. +Class method to return the current thread's context. This returns the same +value as running L inside the current +thread's entry point function. =head1 THREAD STACK SIZE @@ -613,9 +613,9 @@ By tuning the stack size to more accurately reflect your application's needs, you may significantly reduce your application's memory usage, and increase the number of simultaneously running threads. -N.B., on Windows, Address space allocation granularity is 64 KB, therefore, -setting the stack smaller than that on Win32 Perl will not save any more -memory. +Note that on Windows, address space allocation granularity is 64 KB, +therefore, setting the stack smaller than that on Win32 Perl will not save any +more memory. =over @@ -668,8 +668,8 @@ threaded applications. =item threads->create({'stack_size' => VALUE}, FUNCTION, ARGS) -The stack size an individual threads may also be specified. This may be done -by calling C<-Ecreate()> with a parameter hash as the first argument: +To specify a particular stack size for any individual thread, call +C<-Ecreate()> with a hash reference as the first argument: my $thr = threads->create({'stack_size' => 32*4096}, \&foo, @args); @@ -746,7 +746,7 @@ and I capabilities: ... } - # Create a semaphore and send it to a thread + # Create a semaphore and pass it to a thread my $sema = Thread::Semaphore->new(); my $thr = threads->create('thr_func', $sema); @@ -799,7 +799,7 @@ cause for the failure. A thread terminated in some manner other than just returning from its entry point function, or by using Cexit()>. For example, the thread -may have terminated because of a error, or by using C. +may have terminated because of an error, or by using C. =item Using minimum thread stack size of # @@ -863,7 +863,7 @@ problem. =item Using non-threadsafe modules -Unfortunately, you may encounter Perl modules are not I. For +Unfortunately, you may encounter Perl modules that are not I. For example, they may crash the Perl interpreter during execution, or may dump core on termination. Depending on the module and the requirements of your application, it may be possible to work around such difficulties. @@ -912,7 +912,7 @@ signalling behavior is only in effect in the following situations: =over 4 -=item * Perl was been built with C (see C). +=item * Perl has been built with C (see C). =item * The environment variable C is set to C (see L). @@ -939,7 +939,7 @@ reconstituting it in the joining thread. =item Perl Bugs and the CPAN Version of L -Support for threads extents beyond the code in this module (i.e., +Support for threads extends beyond the code in this module (i.e., F and F), and into the Perl iterpreter itself. Older versions of Perl contain bugs that may manifest themselves despite using the latest version of L from CPAN. There is no workaround for this other @@ -957,7 +957,7 @@ L Discussion Forum on CPAN: L Annotated POD for L: -L +L L, L