+=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 is another older Perl threading flavor called the 5.005 model
-that used the L<Threads> class. This old model is known to have problems, is
-deprecated, and support for it will be removed in release 5.10. You are
+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
+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
do it.
However, it is important to remember that Perl threads cannot magically
-do things unless your operating system's threads allows it. So if your
+do things unless your operating system's threads allow it. So if your
system blocks the entire process on C<sleep()>, Perl usually will, as well.
B<Perl Threads Are Different.>
=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.
like:
use Config;
- $Config{useithreads} or die('Recompile Perl with threads to run this program.');
+ $Config{useithreads} or
+ die('Recompile Perl with threads to run this program.');
A possibly-threaded program using a possibly-threaded module might
have code like this:
sub sub1 {
my @InboundParameters = @_;
print("In the thread\n");
- print('Got parameters >', join('<>', @InboundParameters), "<\n");
+ print('Got parameters >', join('<>',@InboundParameters), "<\n");
}
The last example illustrates another feature of threads. You can spawn
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
sleep(15); # Let thread run for awhile
sub sub1 {
- $a = 0;
+ my $count = 0;
while (1) {
- $a++;
- print("\$a is $a\n");
+ $count++;
+ print("\$count is $count\n");
sleep(1);
}
}
# 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.
... create some threads ...
- $hash{a} = 1; # All threads see exists($hash{a}) and $hash{a} == 1
+ $hash{a} = 1; # All threads see exists($hash{a})
+ # and $hash{a} == 1
$hash{a} = $var; # okay - copy-by-value: same effect as previous
$hash{a} = $svar; # okay - copy-by-value: same effect as previous
$hash{a} = \$svar; # okay - a reference to a shared variable
use threads;
use threads::shared;
- my $a :shared = 1;
+ my $x :shared = 1;
my $thr1 = threads->create(\&sub1);
my $thr2 = threads->create(\&sub2);
- $thr1->join;
- $thr2->join;
- print("$a\n");
+ $thr1->join();
+ $thr2->join();
+ print("$x\n");
- sub sub1 { my $foo = $a; $a = $foo + 1; }
- sub sub2 { my $bar = $a; $a = $bar + 1; }
+ sub sub1 { my $foo = $x; $x = $foo + 1; }
+ sub sub2 { my $bar = $x; $x = $bar + 1; }
-What do you think C<$a> will be? The answer, unfortunately, is I<it
-depends>. Both C<sub1()> and C<sub2()> access the global variable C<$a>, once
+What do you think C<$x> will be? The answer, unfortunately, is I<it
+depends>. Both C<sub1()> and C<sub2()> access the global variable C<$x>, once
to read and once to write. Depending on factors ranging from your
thread implementation's scheduling algorithm to the phase of the moon,
-C<$a> can be 2 or 3.
+C<$x> can be 2 or 3.
Race conditions are caused by unsynchronized access to shared
data. Without explicit synchronization, there's no way to be sure that
possibility of error:
use threads;
- my $a :shared = 2;
- my $b :shared;
- 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;
+ my $x :shared = 2;
+ my $y :shared;
+ my $z :shared;
+ my $thr1 = threads->create(sub { $y = $x; $x = $y + 1; });
+ my $thr2 = threads->create(sub { $z = $x; $x = $z + 1; });
+ $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
-or 4, and both C<$b> and C<$c> could be 2 or 3.
+Two threads both access C<$x>. Each thread can potentially be interrupted
+at any point, or be executed in any order. At the end, C<$x> could be 3
+or 4, and both C<$y> and C<$z> could be 2 or 3.
-Even C<$a += 5> or C<$a++> are not guaranteed to be atomic.
+Even C<$x += 5> or C<$x++> are not guaranteed to be atomic.
Whenever your program accesses data or resources that can be accessed
by other threads, you must take steps to coordinate access or risk
use threads;
- my $a :shared = 4;
- my $b :shared = 'foo';
+ my $x :shared = 4;
+ my $y :shared = 'foo';
my $thr1 = threads->create(sub {
- lock($a);
+ lock($x);
sleep(20);
- lock($b);
+ lock($y);
});
my $thr2 = threads->create(sub {
- lock($b);
+ lock($y);
sleep(20);
- lock($a);
+ lock($x);
});
This program will probably hang until you kill it. The only way it
first. A guaranteed-to-hang version is more complicated, but the
principle is the same.
-The first thread will grab a lock on C<$a>, then, after a pause during which
+The first thread will grab a lock on C<$x>, then, after a pause during which
the second thread has probably had time to do some work, try to grab a
-lock on C<$b>. Meanwhile, the second thread grabs a lock on C<$b>, then later
-tries to grab a lock on C<$a>. The second lock attempt for both threads will
+lock on C<$y>. Meanwhile, the second thread grabs a lock on C<$y>, then later
+tries to grab a lock on C<$x>. The second lock attempt for both threads will
block, each waiting for the other to release its lock.
This condition is called a deadlock, and it occurs whenever two or
There are a number of ways to handle this sort of problem. The best
way is to always have all threads acquire locks in the exact same
-order. If, for example, you lock variables C<$a>, C<$b>, and C<$c>, always lock
-C<$a> before C<$b>, and C<$b> before C<$c>. It's also best to hold on to locks for
+order. If, for example, you lock variables C<$x>, C<$y>, and C<$z>, always lock
+C<$x> before C<$y>, and C<$y> before C<$z>. It's also best to hold on to locks for
as short a period of time to minimize the risks of deadlock.
The other synchronization primitives described below can suffer from
$DataQueue->enqueue(12);
$DataQueue->enqueue("A", "B", "C");
- $DataQueue->enqueue(\$thr);
sleep(10);
$DataQueue->enqueue(undef);
$thr->join();
=head2 Basic semaphores
Semaphores have two methods, C<down()> and C<up()>: C<down()> decrements the resource
-count, while up() increments it. Calls to C<down()> will block if the
+count, while C<up()> increments it. Calls to C<down()> will block if the
semaphore's current count would decrement below zero. This program
gives a quick demonstration:
while ($TryCount--) {
$semaphore->down();
$LocalCopy = $GlobalVariable;
- print("$TryCount tries left for sub $SubNumber (\$GlobalVariable is $GlobalVariable)\n");
+ print("$TryCount tries left for sub $SubNumber "
+ ."(\$GlobalVariable is $GlobalVariable)\n");
sleep(2);
$LocalCopy++;
$GlobalVariable = $LocalCopy;
If C<down()> attempts to decrement the counter below zero, it blocks until
the counter is large enough. Note that while a semaphore can be created
with a starting count of zero, any C<up()> or C<down()> always changes the
-counter by at least one, and so C<$semaphore->down(0)> is the same as
-C<$semaphore->down(1)>.
+counter by at least one, and so C<< $semaphore->down(0) >> is the same as
+C<< $semaphore->down(1) >>.
The question, of course, is why would you do something like this? Why
create a semaphore with a starting count that's not one, or why
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.
Larger increments or decrements are handy in those cases where a
thread needs to check out or return a number of resources at once.
-=head2 cond_wait() and cond_signal()
+=head2 Waiting for a Condition
-These two functions can be used in conjunction with locks to notify
+The functions C<cond_wait()> and C<cond_signal()>
+can be used in conjunction with locks to notify
co-operating threads that a resource has become available. They are
very similar in use to the functions found in C<pthreads>. However
for most purposes, queues are simpler to use and more intuitive. See
thread the object represents. Thread IDs are integers, with the main
thread in a program being 0. Currently Perl assigns a unique TID to
every thread ever created in your program, assigning the first thread
-to be created a tid of 1, and increasing the tid by 1 for each new
+to be created a TID of 1, and increasing the TID by 1 for each new
thread that's created. When used as a class method, C<threads-E<gt>tid()>
can be used by a thread to get its own TID.
Confused yet? It's time for an example program to show some of the
things we've covered. This program finds prime numbers using threads.
- 1 #!/usr/bin/perl
- 2 # prime-pthread, courtesy of Tom Christiansen
- 3
- 4 use strict;
- 5 use warnings;
- 6
- 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 }
+ 1 #!/usr/bin/perl
+ 2 # prime-pthread, courtesy of Tom Christiansen
+ 3
+ 4 use strict;
+ 5 use warnings;
+ 6
+ 7 use threads;
+ 8 use Thread::Queue;
+ 9
+ 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.
Since kernel threading can interrupt a thread at any time, they will
uncover some of the implicit locking assumptions you may make in your
-program. For example, something as simple as C<$a = $a + 2> can behave
-unpredictably with kernel threads if C<$a> is visible to other
-threads, as another thread may have changed C<$a> between the time it
+program. For example, something as simple as C<$x = $x + 2> can behave
+unpredictably with kernel threads if C<$x> is visible to other
+threads, as another thread may have changed C<$x> between the time it
was fetched on the right hand side and the time the new value is
stored.
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
Whether various library calls are thread-safe is outside the control
of Perl. Calls often suffering from not being thread-safe include:
-C<localtime()>, C<gmtime()>, C<get{gr,host,net,proto,serv,pw}*()>, C<readdir()>,
-C<rand()>, and C<srand()> -- in general, calls that depend on some global
-external state.
+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.
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
+L<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