use strict;
use warnings;
-our $VERSION = '1.59_01';
+our $VERSION = '1.64';
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;
} 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.59
+This document describes threads version 1.64
=head1 SYNOPSIS
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);
=over
+=item Threadsafe modules
+
+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-threadsafe modules
Unfortunately, you may encounter Perl modules that are not I<threadsafe>. For
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
latest version of L<threads> from CPAN. There is no workaround for this other
than upgrading to the lastest version of Perl.
+Even with the lastest 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.
+
=back
=head1 REQUIREMENTS
L<http://www.cpanforum.com/dist/threads>
Annotated POD for L<threads>:
-L<http://annocpan.org/~JDHEDDEN/threads-1.59/threads.pm>
+L<http://annocpan.org/~JDHEDDEN/threads-1.64/threads.pm>
+
+Source repository:
+L<http://code.google.com/p/threads-shared/>
L<threads::shared>, L<perlthrtut>