use strict;
use warnings;
-our $VERSION = '1.56';
+our $VERSION = '1.71';
my $XS_VERSION = $VERSION;
$VERSION = eval $VERSION;
+# Verify this Perl supports threads
+require Config;
+if (! $Config::Config{useithreads}) {
+ die("This Perl not built to support threads\n");
+}
-BEGIN {
- # Verify this Perl supports threads
- use Config;
- if (! $Config{useithreads}) {
- die("This Perl not built to support threads\n");
- }
-
- # Complain if 'threads' is loaded after 'threads::shared'
- if ($threads::shared::threads_shared) {
- warn <<'_MSG_';
+# Complain if 'threads' is loaded after 'threads::shared'
+if ($threads::shared::threads_shared) {
+ warn <<'_MSG_';
Warning, threads::shared has already been loaded. To
enable shared variables, 'use threads' must be called
before threads::shared or any module that uses it.
_MSG_
- }
}
-
# Declare that we have been loaded
$threads::threads = 1;
# Handle args
while (my $sym = shift) {
- if ($sym =~ /^stack/i) {
- threads->set_stack_size(shift);
-
- } elsif ($sym =~ /^exit/i) {
- my $flag = shift;
- $threads::thread_exit_only = $flag =~ /^thread/i;
+ if ($sym =~ /^(?:stack|exit)/i) {
+ if (defined(my $arg = shift)) {
+ if ($sym =~ /^stack/i) {
+ threads->set_stack_size($arg);
+ } else {
+ $threads::thread_exit_only = $arg =~ /^thread/i;
+ }
+ } else {
+ require Carp;
+ Carp::croak("threads: Missing argument for option: $sym");
+ }
} elsif ($sym =~ /^str/i) {
import overload ('""' => \&tid);
- } elsif ($sym =~ /(?:all|yield)/) {
+ } elsif ($sym =~ /^(?::all|yield)$/) {
push(@EXPORT, qw(yield));
} else {
# Class method only
if (ref($class)) {
require Carp;
- Carp::croak("Usage: threads->exit(status)");
+ Carp::croak('Usage: threads->exit(status)');
}
$class->set_thread_exit_only(1);
=head1 VERSION
-This document describes threads version 1.56
+This document describes threads version 1.71
=head1 SYNOPSIS
The I<threads> API is loosely based on the old Thread.pm API. It is very
important to note that variables are not shared between threads, all variables
-are by default thread local. To use shared variables one must use
-L<threads::shared>.
+are by default thread local. To use shared variables one must also use
+L<threads::shared>:
+
+ use threads;
+ use threads::shared;
It is also important to note that you must enable threads by doing C<use
threads> as early as possible in the script itself, and that it is not
returns a count of the same.
With a I<true> argument (using C<threads::running>), returns a list of all
-non-detached I<threads> objects that are still running.
+non-joined, non-detached I<threads> objects that are still running.
With a I<false> argument (using C<threads::joinable>), returns a list of all
non-joined, non-detached I<threads> objects that have finished running (i.e.,
C<async> 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 C<threads->create()>, C<async>
+semicolon after the closing brace. Like C<threads-E<gt>create()>, C<async>
returns a I<threads> object.
=item $thr->error()
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<exit()> inside a
thread, and effectively causes such calls to behave the same as
=item $thr->set_thread_exit_only(boolean)
This can be used to change the I<exit thread only> behavior for a thread after
-it has been created. With a I<true> argument, C<exit()> will cause the only
-the thread to exit. With a I<false> argument, C<exit()> will terminate the
+it has been created. With a I<true> argument, C<exit()> will cause only the
+thread to exit. With a I<false> argument, C<exit()> will terminate the
application.
The I<main> 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<exit()>.
+Class method for use inside a thread to change its own behavior for C<exit()>.
The I<main> thread is unaffected by this call.
=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<block>.
+yet been joined. In other words, the thread is ready to be joined, and a call
+to C<$thr-E<gt>join()> will not I<block>.
=item $thr->is_detached()
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<-E<gt>create()> with a parameter hash
+function. This may be done by calling C<-E<gt>create()> with a hash reference
as the first argument:
my $thr = threads->create({'context' => 'list'}, \&foo);
In the above, the threads object is returned to the parent thread in scalar
context, and the thread's entry point function C<foo> will be called in list
-context such that the parent thread can receive a list from the C<-E<gt>join()>
-call. Similarly, if you need the threads object, but your thread will not be
+(array) context such that the parent thread can receive a list (array) from
+the C<-E<gt>join()> call. (C<'array'> is synonymous with C<'list'>.)
+
+Similarly, if you need the threads object, but your thread will not be
returning a value (i.e., I<void> context), you would do the following:
my $thr = threads->create({'context' => 'void'}, \&foo);
...
$thr->join();
-The context type may also be used as the I<key> in the parameter hash followed
+The context type may also be used as the I<key> in the hash reference followed
by a I<true> value:
threads->create({'scalar' => 1}, \&foo);
=head2 threads->wantarray()
-Class method to return the current thread's context. This is the same as
-running L<wantarray()|perlfunc/"wantarray"> in the current thread.
+Class method to return the current thread's context. This returns the same
+value as running L<wantarray()|perlfunc/"wantarray"> inside the current
+thread's entry point function.
=head1 THREAD STACK SIZE
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
=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<-E<gt>create()> with a parameter hash as the first argument:
+To specify a particular stack size for any individual thread, call
+C<-E<gt>create()> with a hash reference as the first argument:
my $thr = threads->create({'stack_size' => 32*4096}, \&foo, @args);
...
}
- # 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);
A thread terminated in some manner other than just returning from its entry
point function, or by using C<threads-E<gt>exit()>. For example, the thread
-may have terminated because of a error, or by using C<die>.
+may have terminated because of an error, or by using C<die>.
=item Using minimum thread stack size of #
=over
-=item Using non-threadsafe modules
+=item Thread-safe modules
-Unfortunately, you may encounter Perl modules are not I<threadsafe>. For
-example, they may crash the Perl interpreter during execution, or may dump
+See L<perlmod/"Making your module threadsafe"> when creating modules that may
+be used in threaded applications, especially if those modules use non-Perl
+data, or XS code.
+
+=item Using non-thread-safe modules
+
+Unfortunately, you may encounter Perl modules that are not I<thread-safe>.
+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.
sub thr_func
{
require Unsafe::Module
- # import Unsafe::Module ...;
+ # Unsafe::Module->import(...);
....
}
If the module is needed inside the I<main> thread, try modifying your
application so that the module is loaded (again using C<require> and
-C<import>) after any threads are started, and in such a way that no other
-threads are started afterwards.
+C<-E<gt>import()>) after any threads are started, and in such a way that no
+other threads are started afterwards.
If the above does not work, or is not adequate for your application, then file
a bug report on L<http://rt.cpan.org/Public/> against the problematic module.
+=item Current working directory
+
+On all platforms except MSWin32, the setting for the current working directory
+is shared among all threads such that changing it in one thread (e.g., using
+C<chdir()>) will affect all the threads in the application.
+
+On MSWin32, each thread maintains its own the current working directory
+setting.
+
+=item Environment variables
+
+Currently, on all platforms except MSWin32, all I<system> calls (e.g., using
+C<system()> or back-ticks) made from threads use the environment variable
+settings from the I<main> thread. In other words, changes made to C<%ENV> in
+a thread will not be visible in I<system> calls made by that thread.
+
+To work around this, set environment variables as part of the I<system> call.
+For example:
+
+ my $msg = 'hello';
+ system("FOO=$msg; echo \$FOO"); # Outputs 'hello' to STDOUT
+
+On MSWin32, each thread maintains its own set of environment variables.
+
=item Parent-child threads
On some platforms, it might not be possible to destroy I<parent> threads while
=over 4
-=item * Perl was been built with C<PERL_OLD_SIGNALS> (see C<perl -V>).
+=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">).
Returning objects from threads does not work. Depending on the classes
involved, you may be able to work around this by returning a serialized
version of the object (e.g., using L<Data::Dumper> or L<Storable>), and then
-reconstituting it in the joining thread.
+reconstituting it in the joining thread. If you're using Perl 5.10.0 or
+later, and if the class supports L<shared objects|threads::shared/"OBJECTS">,
+you can pass them via L<shared queues| Thread::Queue>.
+
+=item END blocks in threads
+
+It is possible to add L<END blocks|perlmod/"BEGIN, UNITCHECK, CHECK, INIT and
+END"> to threads by using L<require|perlfunc/"require VERSION"> or
+L<eval|perlfunc/"eval EXPR"> with the appropriate code. These C<END> blocks
+will then be executed when the thread's interpreter is destroyed (i.e., either
+during a C<-E<gt>join()> call, or at program termination).
+
+However, calling any L<threads> methods in such an C<END> block will most
+likely I<fail> (e.g., the application may hang, or generate an error) due to
+mutexes that are needed to control functionality within the L<threads> module.
+
+For this reason, the use of C<END> blocks in threads is B<strongly>
+discouraged.
=item Perl Bugs and the CPAN Version of L<threads>
-Support for threads extents beyond the code in this module (i.e.,
-F<threads.pm> and F<threads.xs>), and into the Perl iterpreter itself. Older
+Support for threads extends beyond the code in this module (i.e.,
+F<threads.pm> and F<threads.xs>), and into the Perl interpreter itself. Older
versions of Perl contain bugs that may manifest themselves despite using the
latest version of L<threads> from CPAN. There is no workaround for this other
-than upgrading to the lastest version of Perl.
+than upgrading to the latest version of Perl.
+
+Even with the latest version of Perl, it is known that certain constructs
+with threads may result in warning messages concerning leaked scalars or
+unreferenced scalars. However, such warnings are harmless, and may safely be
+ignored.
+
+You can search for L<threads> related bug reports at
+L<http://rt.cpan.org/Public/>. If needed submit any new bugs, problems,
+patches, etc. to: L<http://rt.cpan.org/Public/Dist/Display.html?Name=threads>
=back
L<http://www.cpanforum.com/dist/threads>
Annotated POD for L<threads>:
-L<http://annocpan.org/~JDHEDDEN/threads-1.56/threads.pm>
+L<http://annocpan.org/~JDHEDDEN/threads-1.71/threads.pm>
+
+Source repository:
+L<http://code.google.com/p/threads-shared/>
L<threads::shared>, L<perlthrtut>
Artur Bergman E<lt>sky AT crucially DOT netE<gt>
-threads is released under the same license as Perl.
-
CPAN version produced by Jerry D. Hedden <jdhedden AT cpan DOT org>
+=head1 LICENSE
+
+threads is released under the same license as Perl.
+
=head1 ACKNOWLEDGEMENTS
Richard Soderberg E<lt>perl AT crystalflame DOT netE<gt> -
projects / p5sagit/p5-mst-13.2.git / blobdiff