package Thread;
-$VERSION = '2.00';
-
use strict;
+use warnings;
+no warnings 'redefine';
-our $ithreads;
-our $othreads;
+our $VERSION = '3.02';
+$VERSION = eval $VERSION;
BEGIN {
use Config;
- $ithreads = $Config{useithreads};
- $othreads = $Config{use5005threads};
+ if (! $Config{useithreads}) {
+ die("This Perl not built to support threads\n");
+ }
}
+use threads 'yield';
+use threads::shared;
+
require Exporter;
-use XSLoader ();
-our($VERSION, @ISA, @EXPORT, @EXPORT_OK);
+our @ISA = qw(Exporter threads);
+our @EXPORT = qw(cond_wait cond_broadcast cond_signal);
+our @EXPORT_OK = qw(async yield);
-@ISA = qw(Exporter);
+sub async (&;@) { return Thread->new(shift); }
-BEGIN {
- if ($ithreads) {
- @EXPORT = qw(share cond_wait cond_broadcast cond_signal unlock)
- } elsif ($othreads) {
- @EXPORT_OK = qw(cond_signal cond_broadcast cond_wait);
- }
- push @EXPORT_OK, qw(async yield);
-}
+sub done { return ! shift->is_running(); }
+
+sub eval { die("'eval' not implemented with 'ithreads'\n"); };
+sub flags { die("'flags' not implemented with 'ithreads'\n"); };
+
+1;
+
+__END__
=head1 NAME
-Thread - manipulate threads in Perl
+Thread - Manipulate threads in Perl (for old code only)
+
+=head1 DEPRECATED
-=head1 CAVEAT
+The C<Thread> module served as the frontend to the old-style thread model,
+called I<5005threads>, that was introduced in release 5.005. That model was
+deprecated, and has been removed in version 5.10.
-Perl has two thread models.
+For old code and interim backwards compatibility, the C<Thread> module has
+been reworked to function as a frontend for the new interpreter threads
+(I<ithreads>) model. However, some previous functionality is not available.
+Further, the data sharing models between the two thread models are completely
+different, and anything to do with data sharing has to be thought differently.
+With I<ithreads>, you must explicitly C<share()> variables between the
+threads.
-In Perl 5.005 the thread model was that all data is implicitly shared
-and shared access to data has to be explicitly synchronized.
-This model is called "5005threads".
+You are strongly encouraged to migrate any existing threaded code to the new
+model (i.e., use the C<threads> and C<threads::shared> modules) as soon as
+possible.
-In Perl 5.6 a new model was introduced in which all is was thread
-local and shared access to data has to be explicitly declared.
-This model is called "ithreads", for "interpreter threads".
+=head1 HISTORY
-In Perl 5.6 the ithreads model was not available as a public API,
-only as an internal API that was available for extension writers,
-and to implement fork() emulation on Win32 platforms.
+In Perl 5.005, the thread model was that all data is implicitly shared, and
+shared access to data has to be explicitly synchronized. This model is called
+I<5005threads>.
-In Perl 5.8 the ithreads model became available through the C<threads>
-module.
+In Perl 5.6, a new model was introduced in which all is was thread local and
+shared access to data has to be explicitly declared. This model is called
+I<ithreads>, for "interpreter threads".
-Neither model is configured by default into Perl (except, as mentioned
-above, in Win32 ithreads are always available.)
+In Perl 5.6, the I<ithreads> model was not available as a public API; only as
+an internal API that was available for extension writers, and to implement
+fork() emulation on Win32 platforms.
-For backwards compatibility, the Thread module has been reworked
-to function as a frontend for both 5005threads and ithreads.
-Note that the compatibility is not complete: because the data sharing
-models are directly opposed, anything to do with data sharing has to
-be thought differently. With the ithreads you must explicitly share()
-variables between the threads.
+In Perl 5.8, the I<ithreads> model became available through the C<threads>
+module, and the I<5005threads> model was deprecated.
-Finally, note that there are many known serious problems with the
-5005threads, one of the least of which is that regular expression
-match variables like $1 are not threadsafe, that is, they easily get
-corrupted by competing threads. Other problems include more insidious
-data corruption and mysterious crashes. You are seriously urged to
-use ithreads instead.
+In Perl 5.10, the I<5005threads> model was removed from the Perl interpreter.
=head1 SYNOPSIS
- use Thread;
+ use Thread qw(:DEFAULT async yield);
my $t = Thread->new(\&start_sub, @start_args);
$result = $t->join;
- $result = $t->eval;
$t->detach;
if ($t->done) {
}
if($t->equal($another_thread)) {
- # ...
+ # ...
}
yield();
- my $tid = Thread->self->tid;
+ my $tid = Thread->self->tid;
lock($scalar);
lock(@array);
lock(%hash);
- lock(\&sub); # not available with ithreads
-
- $flags = $t->flags; # not available with ithreads
-
- my @list = Thread->list; # not available with ithreads
-
- unlock(...); # not available with the 5.005 threads
-
- use Thread 'async';
+ my @list = Thread->list;
=head1 DESCRIPTION
-The C<Thread> module provides multithreading support for perl.
+The C<Thread> module provides multithreading support for Perl.
=head1 FUNCTIONS
=item lock VARIABLE
-C<lock> places a lock on a variable until the lock goes out of scope
-(with ithreads you can also explicitly unlock()).
+C<lock> places a lock on a variable until the lock goes out of scope.
If the variable is locked by another thread, the C<lock> call will
block until it's available. C<lock> is recursive, so multiple calls
does a C<lock @a>, any other thread doing a C<lock($a[12])> won't
block.
-With 5005threads you may also C<lock> a sub, using C<lock &sub>.
-Any calls to that sub from another thread will block until the lock
-is released. This behaviour is not equivalent to declaring the sub
-with the C<locked> attribute. The C<locked> attribute serializes
-access to a subroutine, but allows different threads non-simultaneous
-access. C<lock &sub>, on the other hand, will not allow I<any> other
-thread access for the duration of the lock.
-
Finally, C<lock> will traverse up references exactly I<one> level.
C<lock(\$a)> is equivalent to C<lock($a)>, while C<lock(\\$a)> is not.
The C<Thread-E<gt>self> function returns a thread object that represents
the thread making the C<Thread-E<gt>self> call.
+=item Thread->list
+
+Returns a list of all non-joined, non-detached Thread objects.
+
=item cond_wait VARIABLE
The C<cond_wait> function takes a B<locked> variable as
the C<join> to die as well, you should either wrap the C<join> in
an C<eval> or use the C<eval> thread method instead of C<join>.
-=item eval
-
-The C<eval> method wraps an C<eval> around a C<join>, and so waits for
-a thread to exit, passing along any values the thread might have returned.
-Errors, of course, get placed into C<$@>. (Not available with ithreads.)
-
=item detach
C<detach> tells a thread that it is never going to be joined i.e.
Errors in detached threads will not be visible anywhere - if you want
to catch them, you should use $SIG{__DIE__} or something like that.
-=item equal
+=item equal
C<equal> tests whether two thread objects represent the same thread and
returns true if they do.
created. The main thread of a program will have a tid of zero,
while subsequent threads will have tids assigned starting with one.
-=item flags
-
-The C<flags> method returns the flags for the thread. This is the
-integer value corresponding to the internal flags for the thread,
-and the value may not be all that meaningful to you.
-(Not available with ithreads.)
-
=item done
The C<done> method returns true if the thread you're checking has
-finished, and false otherwise. (Not available with ithreads.)
+finished, and false otherwise.
=back
-=head1 LIMITATIONS
+=head1 DEFUNCT
-The sequence number used to assign tids is a simple integer, and no
-checking is done to make sure the tid isn't currently in use. If a
-program creates more than 2**32 - 1 threads in a single run, threads
-may be assigned duplicate tids. This limitation may be lifted in
-a future version of Perl.
+The following were implemented with I<5005threads>, but are no longer
+available with I<ithreads>.
-=head1 SEE ALSO
+=over 8
-L<threads::shared> (not available with 5005threads)
+=item lock(\&sub)
-L<attributes>, L<Thread::Queue>, L<Thread::Semaphore>,
-L<Thread::Specific> (not available with ithreads)
+With 5005threads, you could also C<lock> a sub such that any calls to that sub
+from another thread would block until the lock was released.
-=cut
+Also, subroutines could be declared with the C<:locked> attribute which would
+serialize access to the subroutine, but allowed different threads
+non-simultaneous access.
-#
-# Methods
-#
-
-#
-# Exported functions
-#
+=item eval
-sub async (&) {
- return Thread->new($_[0]);
-}
+The C<eval> method wrapped an C<eval> around a C<join>, and so waited for a
+thread to exit, passing along any values the thread might have returned and
+placing any errors into C<$@>.
-sub eval {
- return eval { shift->join; };
-}
+=item flags
-sub unimplemented {
- print $_[0], " unimplemented with ",
- $Config{useithreads} ? "ithreads" : "5005threads", "\n";
+The C<flags> method returned the flags for the thread - an integer value
+corresponding to the internal flags for the thread.
-}
+=back
-sub unimplement {
- for my $m (@_) {
- no strict 'refs';
- *{"Thread::$m"} = sub { unimplemented $m };
- }
-}
+=head1 SEE ALSO
-BEGIN {
- if ($ithreads) {
- XSLoader::load 'threads';
- for my $m (qw(new join detach yield self tid equal)) {
- no strict 'refs';
- *{"Thread::$m"} = \&{"threads::$m"};
- }
- XSLoader::load 'threads::shared';
- for my $m (qw(cond_signal cond_broadcast cond_wait unlock share)) {
- no strict 'refs';
- *{"Thread::$m"} = \&{"threads::shared::${m}_enabled"};
- }
- # trying to unimplement eval gives redefined warning
- unimplement(qw(list done flags));
- } elsif ($othreads) {
- XSLoader::load 'Thread';
- unimplement(qw(unlock));
- } else {
- require Carp;
- Carp::croak("This Perl has neither ithreads not 5005threads");
- }
-}
+L<threads>, L<threads::shared>, L<Thread::Queue>, L<Thread::Semaphore>
-1;
+=cut
https://perl5.git.perl.org / perl5.git / blobdiff