+=encoding utf8
+
=head1 NAME
perlthrtut - Tutorial on threads in Perl
=head1 DESCRIPTION
This tutorial describes the use of Perl interpreter threads (sometimes
-referred to as I<ithreads>) that was first introduced in Perl 5.6.0. In this
+referred to as I<ithreads>). In this
model, each thread runs in its own Perl interpreter, and any data sharing
between threads must be explicit. The user-level interface for I<ithreads>
uses the L<threads> class.
B<NOTE>: There was another older Perl threading flavor called the 5.005 model
-that used the L<Threads> class. This old model was known to have problems, is
+that used the L<threads> class. This old model was known to have problems, is
deprecated, and was removed for release 5.10. You are
strongly encouraged to migrate any existing 5.005 threads code to the new
model as soon as possible.
disappointed or confused. Possibly both.
This is not to say that Perl threads are completely different from
-everything that's ever come before -- they're not. Perl's threading
+everything that's ever come before. They're not. Perl's threading
model owes a lot to other thread models, especially POSIX. Just as
Perl is not C, though, Perl threads are not POSIX threads. So if you
find yourself looking for mutexes, or thread priorities, it's time to
=head2 Basic Thread Support
-Thread support is a Perl compile-time option -- it's something that's
+Thread support is a Perl compile-time option. It's something that's
turned on or off when Perl is built at your site, rather than when
your programs are compiled. If your Perl wasn't compiled with thread
support enabled, then any attempt to use threads will fail.
NOTE: In the example above, the thread returns a list, thus necessitating
that the thread creation call be made in list context (i.e., C<my ($thr)>).
-See L<threads/"$thr->join()"> and L<threads/"THREAD CONTEXT"> for more
+See L<< threads/"$thr->join()" >> and L<threads/"THREAD CONTEXT"> for more
details on thread context and return values.
=head2 Ignoring A Thread
# Do more work
}
+=head2 Process and Thread Termination
+
+With threads one must be careful to make sure they all have a chance to
+run to completion, assuming that is what you want.
+
+An action that terminates a process will terminate I<all> running
+threads. die() and exit() have this property,
+and perl does an exit when the main thread exits,
+perhaps implicitly by falling off the end of your code,
+even if that's not what you want.
+
+As an example of this case, this code prints the message
+"Perl exited with active threads: 2 running and unjoined":
+
+ use threads;
+ my $thr1 = threads->new(\&thrsub, "test1");
+ my $thr2 = threads->new(\&thrsub, "test2");
+ sub thrsub {
+ my ($message) = @_;
+ sleep 1;
+ print "thread $message\n";
+ }
+
+But when the following lines are added at the end:
+
+ $thr1->join();
+ $thr2->join();
+
+it prints two lines of output, a perhaps more useful outcome.
+
=head1 Threads And Data
Now that we've covered the basics of threads, it's time for our next
is that by default, no data is shared. When a new Perl thread is created,
all the data associated with the current thread is copied to the new
thread, and is subsequently private to that new thread!
-This is similar in feel to what happens when a UNIX process forks,
+This is similar in feel to what happens when a Unix process forks,
except that in this case, the data is just copied to a different part of
memory within the same process rather than a real fork taking place.
my $thr1 = threads->create(\&sub1);
my $thr2 = threads->create(\&sub2);
- $thr1->join;
- $thr2->join;
+ $thr1->join();
+ $thr2->join();
print("$a\n");
sub sub1 { my $foo = $a; $a = $foo + 1; }
my $c :shared;
my $thr1 = threads->create(sub { $b = $a; $a = $b + 1; });
my $thr2 = threads->create(sub { $c = $a; $a = $c + 1; });
- $thr1->join;
- $thr2->join;
+ $thr1->join();
+ $thr2->join();
Two threads both access C<$a>. Each thread can potentially be interrupted
at any point, or be executed in any order. At the end, C<$a> could be 3
establishing quotas. Say, for example, that you have a number of
threads that can do I/O at once. You don't want all the threads
reading or writing at once though, since that can potentially swamp
-your I/O channels, or deplete your process' quota of filehandles. You
+your I/O channels, or deplete your process's quota of filehandles. You
can use a semaphore initialized to the number of concurrent I/O
requests (or open files) that you want at any one time, and have your
threads quietly block and unblock themselves.
7 use threads;
8 use Thread::Queue;
9
- 10 my $stream = Thread::Queue->new();
- 11 for my $i ( 3 .. 1000 ) {
- 12 $stream->enqueue($i);
- 13 }
- 14 $stream->enqueue(undef);
- 15
- 16 threads->create(\&check_num, $stream, 2);
- 17 $kid->join();
- 18
- 19 sub check_num {
- 20 my ($upstream, $cur_prime) = @_;
- 21 my $kid;
- 22 my $downstream = Thread::Queue->new();
- 23 while (my $num = $upstream->dequeue()) {
- 24 next unless ($num % $cur_prime);
- 25 if ($kid) {
- 26 $downstream->enqueue($num);
- 27 } else {
- 28 print("Found prime $num\n");
- 29 $kid = threads->create(\&check_num, $downstream, $num);
- 30 }
- 31 }
- 32 if ($kid) {
- 33 $downstream->enqueue(undef);
- 34 $kid->join();
- 35 }
- 36 }
+ 10 sub check_num {
+ 11 my ($upstream, $cur_prime) = @_;
+ 12 my $kid;
+ 13 my $downstream = Thread::Queue->new();
+ 14 while (my $num = $upstream->dequeue()) {
+ 15 next unless ($num % $cur_prime);
+ 16 if ($kid) {
+ 17 $downstream->enqueue($num);
+ 18 } else {
+ 19 print("Found prime: $num\n");
+ 20 $kid = threads->create(\&check_num, $downstream, $num);
+ 21 if (! $kid) {
+ 22 warn("Sorry. Ran out of threads.\n");
+ 23 last;
+ 24 }
+ 25 }
+ 26 }
+ 27 if ($kid) {
+ 28 $downstream->enqueue(undef);
+ 29 $kid->join();
+ 30 }
+ 31 }
+ 32
+ 33 my $stream = Thread::Queue->new(3..1000, undef);
+ 34 check_num($stream, 2);
This program uses the pipeline model to generate prime numbers. Each
thread in the pipeline has an input queue that feeds numbers to be
The bulk of the work is done by the C<check_num()> subroutine, which
takes a reference to its input queue and a prime number that it's
responsible for. After pulling in the input queue and the prime that
-the subroutine is checking (line 20), we create a new queue (line 22)
+the subroutine is checking (line 11), we create a new queue (line 13)
and reserve a scalar for the thread that we're likely to create later
-(line 21).
+(line 12).
-The while loop from lines 23 to line 31 grabs a scalar off the input
+The while loop from line 14 to line 26 grabs a scalar off the input
queue and checks against the prime this thread is responsible
-for. Line 24 checks to see if there's a remainder when we divide the
+for. Line 15 checks to see if there's a remainder when we divide the
number to be checked by our prime. If there is one, the number
must not be evenly divisible by our prime, so we need to either pass
-it on to the next thread if we've created one (line 26) or create a
+it on to the next thread if we've created one (line 17) or create a
new thread if we haven't.
-The new thread creation is line 29. We pass on to it a reference to
-the queue we've created, and the prime number we've found.
+The new thread creation is line 20. We pass on to it a reference to
+the queue we've created, and the prime number we've found. In lines 21
+through 24, we check to make sure that our new thread got created, and
+if not, we stop checking any remaining numbers in the queue.
Finally, once the loop terminates (because we got a 0 or C<undef> in the
queue, which serves as a note to terminate), we pass on the notice to our
-child and wait for it to exit if we've created a child (lines 32 and
-35).
+child, and wait for it to exit if we've created a child (lines 27 and
+30).
-Meanwhile, back in the main thread, we first create a queue (line 10) and
-queue up all the numbers from 3 to 1000 for checking (lines 11-13),
-plus a termination notice (line 14). Then we create the initial child
-threads (line 16), passing it the queue and the first prime: 2. Finally,
-we wait for the first child thread to terminate (line 17). Because a
-child won't terminate until its child has terminated, we know that we're
-done once we return from the C<join()>.
+Meanwhile, back in the main thread, we first create a queue (line 33) and
+queue up all the numbers from 3 to 1000 for checking, plus a termination
+notice. Then all we have to do to get the ball rolling is pass the queue
+and the first prime to the C<check_num()> subroutine (line 34).
That's how it works. It's pretty simple; as with many Perl programs,
the explanation is much longer than the program.
thread creation can be quite expensive, both in terms of memory usage and
time spent in creation. The ideal way to reduce these costs is to have a
relatively short number of long-lived threads, all created fairly early
-on -- before the base thread has accumulated too much data. Of course, this
+on (before the base thread has accumulated too much data). Of course, this
may not always be possible, so compromises have to be made. However, after
a thread has been created, its performance and extra memory usage should
be little different than ordinary code.
Thinking of mixing C<fork()> and threads? Please lie down and wait
until the feeling passes. Be aware that the semantics of C<fork()> vary
-between platforms. For example, some UNIX systems copy all the current
+between platforms. For example, some Unix systems copy all the current
threads into the child process, while others only copy the thread that
called C<fork()>. You have been warned!
guarantee that a signal sent to a multi-threaded Perl application
will get intercepted by any particular thread. (However, a recently
added feature does provide the capability to send signals between
-threads. See L<threads/"THREAD SIGNALLING> for more details.)
+threads. See L<threads/THREAD SIGNALLING> for more details.)
=head1 Thread-Safety of System Libraries
of Perl. Calls often suffering from not being thread-safe include:
C<localtime()>, C<gmtime()>, functions fetching user, group and
network information (such as C<getgrent()>, C<gethostent()>,
-C<getnetent()> and so on), C<readdir()>,
-C<rand()>, and C<srand()> -- in general, calls that depend on some global
-external state.
+C<getnetent()> and so on), C<readdir()>, C<rand()>, and C<srand()>. In
+general, calls that depend on some global external state.
If the system Perl is compiled in has thread-safe variants of such
calls, they will be used. Beyond that, Perl is at the mercy of
Annotated POD for L<threads>:
L<http://annocpan.org/?mode=search&field=Module&name=threads>
-Lastest version of L<threads> on CPAN:
+Latest version of L<threads> on CPAN:
L<http://search.cpan.org/search?module=threads>
Annotated POD for L<threads::shared>:
L<http://annocpan.org/?mode=search&field=Module&name=threads%3A%3Ashared>
-Lastest version of L<threads::shared> on CPAN:
+Latest version of L<threads::shared> on CPAN:
L<http://search.cpan.org/search?module=threads%3A%3Ashared>
Perl threads mailing list:
-L<http://lists.cpan.org/showlist.cgi?name=iThreads>
+L<http://lists.perl.org/list/ithreads.html>
=head1 Bibliography
-Here's a short bibliography courtesy of Jürgen Christoffel:
+Here's a short bibliography courtesy of Jürgen Christoffel:
=head2 Introductory Texts
Birrell, Andrew D. An Introduction to Programming with
Threads. Digital Equipment Corporation, 1989, DEC-SRC Research Report
#35 online as
-http://gatekeeper.dec.com/pub/DEC/SRC/research-reports/abstracts/src-rr-035.html
+ftp://ftp.dec.com/pub/DEC/SRC/research-reports/SRC-035.pdf
(highly recommended)
Robbins, Kay. A., and Steven Robbins. Practical Unix Programming: A
=head1 Acknowledgements
Thanks (in no particular order) to Chaim Frenkel, Steve Fink, Gurusamy
-Sarathy, Ilya Zakharevich, Benjamin Sugars, Jürgen Christoffel, Joshua
+Sarathy, Ilya Zakharevich, Benjamin Sugars, Jürgen Christoffel, Joshua
Pritikin, and Alan Burlison, for their help in reality-checking and
polishing this article. Big thanks to Tom Christiansen for his rewrite
of the prime number generator.
Slightly modified by Arthur Bergman to fit the new thread model/module.
-Reworked slightly by Jörg Walter E<lt>jwalt@cpan.org<gt> to be more concise
+Reworked slightly by Jörg Walter E<lt>jwalt@cpan.org<gt> to be more concise
about thread-safety of Perl code.
Rearranged slightly by Elizabeth Mattijsen E<lt>liz@dijkmat.nl<gt> to put
https://perl5.git.perl.org / perl5.git / blobdiff