1PERLTHRTUT(1) Perl Programmers Reference Guide PERLTHRTUT(1)
2
6 perlthrtut - Tutorial on threads in Perl
7
9 This tutorial describes the use of Perl interpreter threads (sometimes
10 referred to as ithreads) that was first introduced in Perl 5.6.0. In
11 this model, each thread runs in its own Perl interpreter, and any data
12 sharing between threads must be explicit. The user-level interface for
13 ithreads uses the threads class.
14 NOTE: There was another older Perl threading flavor called the 5.005
16 model that used the Threads class. This old model was known to have
17 problems, is deprecated, and was removed for release 5.10. You are
18 strongly encouraged to migrate any existing 5.005 threads code to the
19 new model as soon as possible.
20 You can see which (or neither) threading flavour you have by running
22 "perl -V" and looking at the "Platform" section. If you have
23 "useithreads=define" you have ithreads, if you have
24 "use5005threads=define" you have 5.005 threads. If you have neither,
25 you don't have any thread support built in. If you have both, you are
26 in trouble.
27 The threads and threads::shared modules are included in the core Perl
29 distribution. Additionally, they are maintained as a separate modules
30 on CPAN, so you can check there for any updates.
31
33 A thread is a flow of control through a program with a single execution
34 point.
35 Sounds an awful lot like a process, doesn't it? Well, it should.
37 Threads are one of the pieces of a process. Every process has at least
38 one thread and, up until now, every process running Perl had only one
39 thread. With 5.8, though, you can create extra threads. We're going
40 to show you how, when, and why.
41
43 There are three basic ways that you can structure a threaded program.
44 Which model you choose depends on what you need your program to do.
45 For many non-trivial threaded programs, you'll need to choose different
46 models for different pieces of your program.
47 Boss/Worker
49 The boss/worker model usually has one boss thread and one or more
50 worker threads. The boss thread gathers or generates tasks that need
51 to be done, then parcels those tasks out to the appropriate worker
52 thread.
53 This model is common in GUI and server programs, where a main thread
55 waits for some event and then passes that event to the appropriate
56 worker threads for processing. Once the event has been passed on, the
57 boss thread goes back to waiting for another event.
58 The boss thread does relatively little work. While tasks aren't
60 necessarily performed faster than with any other method, it tends to
61 have the best user-response times.
62 Work Crew
64 In the work crew model, several threads are created that do essentially
65 the same thing to different pieces of data. It closely mirrors
66 classical parallel processing and vector processors, where a large
67 array of processors do the exact same thing to many pieces of data.
68 This model is particularly useful if the system running the program
70 will distribute multiple threads across different processors. It can
71 also be useful in ray tracing or rendering engines, where the
72 individual threads can pass on interim results to give the user visual
73 feedback.
74 Pipeline
76 The pipeline model divides up a task into a series of steps, and passes
77 the results of one step on to the thread processing the next. Each
78 thread does one thing to each piece of data and passes the results to
79 the next thread in line.
80 This model makes the most sense if you have multiple processors so two
82 or more threads will be executing in parallel, though it can often make
83 sense in other contexts as well. It tends to keep the individual tasks
84 small and simple, as well as allowing some parts of the pipeline to
85 block (on I/O or system calls, for example) while other parts keep
86 going. If you're running different parts of the pipeline on different
87 processors you may also take advantage of the caches on each processor.
88 This model is also handy for a form of recursive programming where,
90 rather than having a subroutine call itself, it instead creates another
91 thread. Prime and Fibonacci generators both map well to this form of
92 the pipeline model. (A version of a prime number generator is presented
93 later on.)
94
96 If you have experience with other thread implementations, you might
97 find that things aren't quite what you expect. It's very important to
98 remember when dealing with Perl threads that Perl Threads Are Not X
99 Threads for all values of X. They aren't POSIX threads, or DecThreads,
100 or Java's Green threads, or Win32 threads. There are similarities, and
101 the broad concepts are the same, but if you start looking for
102 implementation details you're going to be either disappointed or
103 confused. Possibly both.
104 This is not to say that Perl threads are completely different from
106 everything that's ever come before -- they're not. Perl's threading
107 model owes a lot to other thread models, especially POSIX. Just as
108 Perl is not C, though, Perl threads are not POSIX threads. So if you
109 find yourself looking for mutexes, or thread priorities, it's time to
110 step back a bit and think about what you want to do and how Perl can do
111 it.
112 However, it is important to remember that Perl threads cannot magically
114 do things unless your operating system's threads allow it. So if your
115 system blocks the entire process on "sleep()", Perl usually will, as
116 well.
117 Perl Threads Are Different.
119
121 The addition of threads has changed Perl's internals substantially.
122 There are implications for people who write modules with XS code or
123 external libraries. However, since Perl data is not shared among
124 threads by default, Perl modules stand a high chance of being thread-
125 safe or can be made thread-safe easily. Modules that are not tagged as
126 thread-safe should be tested or code reviewed before being used in
127 production code.
128 Not all modules that you might use are thread-safe, and you should
130 always assume a module is unsafe unless the documentation says
131 otherwise. This includes modules that are distributed as part of the
132 core. Threads are a relatively new feature, and even some of the
133 standard modules aren't thread-safe.
134 Even if a module is thread-safe, it doesn't mean that the module is
136 optimized to work well with threads. A module could possibly be
137 rewritten to utilize the new features in threaded Perl to increase
138 performance in a threaded environment.
139 If you're using a module that's not thread-safe for some reason, you
141 can protect yourself by using it from one, and only one thread at all.
142 If you need multiple threads to access such a module, you can use
143 semaphores and lots of programming discipline to control access to it.
144 Semaphores are covered in "Basic semaphores".
145 See also "Thread-Safety of System Libraries".
147
149 The threads module provides the basic functions you need to write
150 threaded programs. In the following sections, we'll cover the basics,
151 showing you what you need to do to create a threaded program. After
152 that, we'll go over some of the features of the threads module that
153 make threaded programming easier.
154 Basic Thread Support
156 Thread support is a Perl compile-time option -- it's something that's
157 turned on or off when Perl is built at your site, rather than when your
158 programs are compiled. If your Perl wasn't compiled with thread support
159 enabled, then any attempt to use threads will fail.
160 Your programs can use the Config module to check whether threads are
162 enabled. If your program can't run without them, you can say something
163 like:
164 use Config;
166 $Config{useithreads} or die('Recompile Perl with threads to run this program.');
167 A possibly-threaded program using a possibly-threaded module might have
169 code like this:
170 use Config;
172 use MyMod;
173 BEGIN {
175 if ($Config{useithreads}) {
176 # We have threads
177 require MyMod_threaded;
178 import MyMod_threaded;
179 } else {
180 require MyMod_unthreaded;
181 import MyMod_unthreaded;
182 }
183 }
184 Since code that runs both with and without threads is usually pretty
186 messy, it's best to isolate the thread-specific code in its own module.
187 In our example above, that's what "MyMod_threaded" is, and it's only
188 imported if we're running on a threaded Perl.
189 A Note about the Examples
191 In a real situation, care should be taken that all threads are finished
192 executing before the program exits. That care has not been taken in
193 these examples in the interest of simplicity. Running these examples
194 as is will produce error messages, usually caused by the fact that
195 there are still threads running when the program exits. You should not
196 be alarmed by this.
197 Creating Threads
199 The threads module provides the tools you need to create new threads.
200 Like any other module, you need to tell Perl that you want to use it;
201 "use threads;" imports all the pieces you need to create basic threads.
202 The simplest, most straightforward way to create a thread is with
204 "create()":
205 use threads;
207 my $thr = threads->create(\&sub1);
209 sub sub1 {
211 print("In the thread\n");
212 }
213 The "create()" method takes a reference to a subroutine and creates a
215 new thread that starts executing in the referenced subroutine. Control
216 then passes both to the subroutine and the caller.
217 If you need to, your program can pass parameters to the subroutine as
219 part of the thread startup. Just include the list of parameters as
220 part of the "threads->create()" call, like this:
221 use threads;
223 my $Param3 = 'foo';
225 my $thr1 = threads->create(\&sub1, 'Param 1', 'Param 2', $Param3);
226 my @ParamList = (42, 'Hello', 3.14);
227 my $thr2 = threads->create(\&sub1, @ParamList);
228 my $thr3 = threads->create(\&sub1, qw(Param1 Param2 Param3));
229 sub sub1 {
231 my @InboundParameters = @_;
232 print("In the thread\n");
233 print('Got parameters >', join('<>', @InboundParameters), "<\n");
234 }
235 The last example illustrates another feature of threads. You can spawn
237 off several threads using the same subroutine. Each thread executes
238 the same subroutine, but in a separate thread with a separate
239 environment and potentially separate arguments.
240 "new()" is a synonym for "create()".
242 Waiting For A Thread To Exit
244 Since threads are also subroutines, they can return values. To wait
245 for a thread to exit and extract any values it might return, you can
246 use the "join()" method:
247 use threads;
249 my ($thr) = threads->create(\&sub1);
251 my @ReturnData = $thr->join();
253 print('Thread returned ', join(', ', @ReturnData), "\n");
254 sub sub1 { return ('Fifty-six', 'foo', 2); }
256 In the example above, the "join()" method returns as soon as the thread
258 ends. In addition to waiting for a thread to finish and gathering up
259 any values that the thread might have returned, "join()" also performs
260 any OS cleanup necessary for the thread. That cleanup might be
261 important, especially for long-running programs that spawn lots of
262 threads. If you don't want the return values and don't want to wait
263 for the thread to finish, you should call the "detach()" method
264 instead, as described next.
265 NOTE: In the example above, the thread returns a list, thus
267 necessitating that the thread creation call be made in list context
268 (i.e., "my ($thr)"). See ""$thr-" in threadsjoin()"> and "THREAD
269 CONTEXT" in threads for more details on thread context and return
270 values.
271 Ignoring A Thread
273 "join()" does three things: it waits for a thread to exit, cleans up
274 after it, and returns any data the thread may have produced. But what
275 if you're not interested in the thread's return values, and you don't
276 really care when the thread finishes? All you want is for the thread to
277 get cleaned up after when it's done.
278 In this case, you use the "detach()" method. Once a thread is
280 detached, it'll run until it's finished; then Perl will clean up after
281 it automatically.
282 use threads;
284 my $thr = threads->create(\&sub1); # Spawn the thread
286 $thr->detach(); # Now we officially don't care any more
288 sleep(15); # Let thread run for awhile
290 sub sub1 {
292 $a = 0;
293 while (1) {
294 $a++;
295 print("\$a is $a\n");
296 sleep(1);
297 }
298 }
299 Once a thread is detached, it may not be joined, and any return data
301 that it might have produced (if it was done and waiting for a join) is
302 lost.
303 "detach()" can also be called as a class method to allow a thread to
305 detach itself:
306 use threads;
308 my $thr = threads->create(\&sub1);
310 sub sub1 {
312 threads->detach();
313 # Do more work
314 }
315 Process and Thread Termination
317 With threads one must be careful to make sure they all have a chance to
318 run to completion, assuming that is what you want.
319 An action that terminates a process will terminate all running threads.
321 die() and exit() have this property, and perl does an exit when the
322 main thread exits, perhaps implicitly by falling off the end of your
323 code, even if that's not what you want.
324 As an example of this case, this code prints the message "Perl exited
326 with active threads: 2 running and unjoined":
327 use threads;
329 my $thr1 = threads->new(\&thrsub, "test1");
330 my $thr2 = threads->new(\&thrsub, "test2");
331 sub thrsub {
332 my ($message) = @_;
333 sleep 1;
334 print "thread $message\n";
335 }
336 But when the following lines are added at the end:
338 $thr1->join();
340 $thr2->join();
341 it prints two lines of output, a perhaps more useful outcome.
343
345 Now that we've covered the basics of threads, it's time for our next
346 topic: Data. Threading introduces a couple of complications to data
347 access that non-threaded programs never need to worry about.
348 Shared And Unshared Data
350 The biggest difference between Perl ithreads and the old 5.005 style
351 threading, or for that matter, to most other threading systems out
352 there, is that by default, no data is shared. When a new Perl thread is
353 created, all the data associated with the current thread is copied to
354 the new thread, and is subsequently private to that new thread! This
355 is similar in feel to what happens when a UNIX process forks, except
356 that in this case, the data is just copied to a different part of
357 memory within the same process rather than a real fork taking place.
358 To make use of threading, however, one usually wants the threads to
360 share at least some data between themselves. This is done with the
361 threads::shared module and the ":shared" attribute:
362 use threads;
364 use threads::shared;
365 my $foo :shared = 1;
367 my $bar = 1;
368 threads->create(sub { $foo++; $bar++; })->join();
369 print("$foo\n"); # Prints 2 since $foo is shared
371 print("$bar\n"); # Prints 1 since $bar is not shared
372 In the case of a shared array, all the array's elements are shared, and
374 for a shared hash, all the keys and values are shared. This places
375 restrictions on what may be assigned to shared array and hash elements:
376 only simple values or references to shared variables are allowed - this
377 is so that a private variable can't accidentally become shared. A bad
378 assignment will cause the thread to die. For example:
379 use threads;
381 use threads::shared;
382 my $var = 1;
384 my $svar :shared = 2;
385 my %hash :shared;
386 ... create some threads ...
388 $hash{a} = 1; # All threads see exists($hash{a}) and $hash{a} == 1
390 $hash{a} = $var; # okay - copy-by-value: same effect as previous
391 $hash{a} = $svar; # okay - copy-by-value: same effect as previous
392 $hash{a} = \$svar; # okay - a reference to a shared variable
393 $hash{a} = \$var; # This will die
394 delete($hash{a}); # okay - all threads will see !exists($hash{a})
395 Note that a shared variable guarantees that if two or more threads try
397 to modify it at the same time, the internal state of the variable will
398 not become corrupted. However, there are no guarantees beyond this, as
399 explained in the next section.
400 Thread Pitfalls: Races
402 While threads bring a new set of useful tools, they also bring a number
403 of pitfalls. One pitfall is the race condition:
404 use threads;
406 use threads::shared;
407 my $a :shared = 1;
409 my $thr1 = threads->create(\&sub1);
410 my $thr2 = threads->create(\&sub2);
411 $thr1->join();
413 $thr2->join();
414 print("$a\n");
415 sub sub1 { my $foo = $a; $a = $foo + 1; }
417 sub sub2 { my $bar = $a; $a = $bar + 1; }
418 What do you think $a will be? The answer, unfortunately, is it depends.
420 Both "sub1()" and "sub2()" access the global variable $a, once to read
421 and once to write. Depending on factors ranging from your thread
422 implementation's scheduling algorithm to the phase of the moon, $a can
423 be 2 or 3.
424 Race conditions are caused by unsynchronized access to shared data.
426 Without explicit synchronization, there's no way to be sure that
427 nothing has happened to the shared data between the time you access it
428 and the time you update it. Even this simple code fragment has the
429 possibility of error:
430 use threads;
432 my $a :shared = 2;
433 my $b :shared;
434 my $c :shared;
435 my $thr1 = threads->create(sub { $b = $a; $a = $b + 1; });
436 my $thr2 = threads->create(sub { $c = $a; $a = $c + 1; });
437 $thr1->join();
438 $thr2->join();
439 Two threads both access $a. Each thread can potentially be interrupted
441 at any point, or be executed in any order. At the end, $a could be 3
442 or 4, and both $b and $c could be 2 or 3.
443 Even "$a += 5" or "$a++" are not guaranteed to be atomic.
445 Whenever your program accesses data or resources that can be accessed
447 by other threads, you must take steps to coordinate access or risk data
448 inconsistency and race conditions. Note that Perl will protect its
449 internals from your race conditions, but it won't protect you from you.
450
452 Perl provides a number of mechanisms to coordinate the interactions
453 between themselves and their data, to avoid race conditions and the
454 like. Some of these are designed to resemble the common techniques
455 used in thread libraries such as "pthreads"; others are Perl-specific.
456 Often, the standard techniques are clumsy and difficult to get right
457 (such as condition waits). Where possible, it is usually easier to use
458 Perlish techniques such as queues, which remove some of the hard work
459 involved.
460 Controlling access: lock()
462 The "lock()" function takes a shared variable and puts a lock on it.
463 No other thread may lock the variable until the variable is unlocked by
464 the thread holding the lock. Unlocking happens automatically when the
465 locking thread exits the block that contains the call to the "lock()"
466 function. Using "lock()" is straightforward: This example has several
467 threads doing some calculations in parallel, and occasionally updating
468 a running total:
469 use threads;
471 use threads::shared;
472 my $total :shared = 0;
474 sub calc {
476 while (1) {
477 my $result;
478 # (... do some calculations and set $result ...)
479 {
480 lock($total); # Block until we obtain the lock
481 $total += $result;
482 } # Lock implicitly released at end of scope
483 last if $result == 0;
484 }
485 }
486 my $thr1 = threads->create(\&calc);
488 my $thr2 = threads->create(\&calc);
489 my $thr3 = threads->create(\&calc);
490 $thr1->join();
491 $thr2->join();
492 $thr3->join();
493 print("total=$total\n");
494 "lock()" blocks the thread until the variable being locked is
496 available. When "lock()" returns, your thread can be sure that no
497 other thread can lock that variable until the block containing the lock
498 exits.
499 It's important to note that locks don't prevent access to the variable
501 in question, only lock attempts. This is in keeping with Perl's
502 longstanding tradition of courteous programming, and the advisory file
503 locking that "flock()" gives you.
504 You may lock arrays and hashes as well as scalars. Locking an array,
506 though, will not block subsequent locks on array elements, just lock
507 attempts on the array itself.
508 Locks are recursive, which means it's okay for a thread to lock a
510 variable more than once. The lock will last until the outermost
511 "lock()" on the variable goes out of scope. For example:
512 my $x :shared;
514 doit();
515 sub doit {
517 {
518 {
519 lock($x); # Wait for lock
520 lock($x); # NOOP - we already have the lock
521 {
522 lock($x); # NOOP
523 {
524 lock($x); # NOOP
525 lockit_some_more();
526 }
527 }
528 } # *** Implicit unlock here ***
529 }
530 }
531 sub lockit_some_more {
533 lock($x); # NOOP
534 } # Nothing happens here
535 Note that there is no "unlock()" function - the only way to unlock a
537 variable is to allow it to go out of scope.
538 A lock can either be used to guard the data contained within the
540 variable being locked, or it can be used to guard something else, like
541 a section of code. In this latter case, the variable in question does
542 not hold any useful data, and exists only for the purpose of being
543 locked. In this respect, the variable behaves like the mutexes and
544 basic semaphores of traditional thread libraries.
545 A Thread Pitfall: Deadlocks
547 Locks are a handy tool to synchronize access to data, and using them
548 properly is the key to safe shared data. Unfortunately, locks aren't
549 without their dangers, especially when multiple locks are involved.
550 Consider the following code:
551 use threads;
553 my $a :shared = 4;
555 my $b :shared = 'foo';
556 my $thr1 = threads->create(sub {
557 lock($a);
558 sleep(20);
559 lock($b);
560 });
561 my $thr2 = threads->create(sub {
562 lock($b);
563 sleep(20);
564 lock($a);
565 });
566 This program will probably hang until you kill it. The only way it
568 won't hang is if one of the two threads acquires both locks first. A
569 guaranteed-to-hang version is more complicated, but the principle is
570 the same.
571 The first thread will grab a lock on $a, then, after a pause during
573 which the second thread has probably had time to do some work, try to
574 grab a lock on $b. Meanwhile, the second thread grabs a lock on $b,
575 then later tries to grab a lock on $a. The second lock attempt for
576 both threads will block, each waiting for the other to release its
577 lock.
578 This condition is called a deadlock, and it occurs whenever two or more
580 threads are trying to get locks on resources that the others own. Each
581 thread will block, waiting for the other to release a lock on a
582 resource. That never happens, though, since the thread with the
583 resource is itself waiting for a lock to be released.
584 There are a number of ways to handle this sort of problem. The best
586 way is to always have all threads acquire locks in the exact same
587 order. If, for example, you lock variables $a, $b, and $c, always lock
588 $a before $b, and $b before $c. It's also best to hold on to locks for
589 as short a period of time to minimize the risks of deadlock.
590 The other synchronization primitives described below can suffer from
592 similar problems.
593 Queues: Passing Data Around
595 A queue is a special thread-safe object that lets you put data in one
596 end and take it out the other without having to worry about
597 synchronization issues. They're pretty straightforward, and look like
598 this:
599 use threads;
601 use Thread::Queue;
602 my $DataQueue = Thread::Queue->new();
604 my $thr = threads->create(sub {
605 while (my $DataElement = $DataQueue->dequeue()) {
606 print("Popped $DataElement off the queue\n");
607 }
608 });
609 $DataQueue->enqueue(12);
611 $DataQueue->enqueue("A", "B", "C");
612 sleep(10);
613 $DataQueue->enqueue(undef);
614 $thr->join();
615 You create the queue with "Thread::Queue->new()". Then you can add
617 lists of scalars onto the end with "enqueue()", and pop scalars off the
618 front of it with "dequeue()". A queue has no fixed size, and can grow
619 as needed to hold everything pushed on to it.
620 If a queue is empty, "dequeue()" blocks until another thread enqueues
622 something. This makes queues ideal for event loops and other
623 communications between threads.
624 Semaphores: Synchronizing Data Access
626 Semaphores are a kind of generic locking mechanism. In their most basic
627 form, they behave very much like lockable scalars, except that they
628 can't hold data, and that they must be explicitly unlocked. In their
629 advanced form, they act like a kind of counter, and can allow multiple
630 threads to have the lock at any one time.
631 Basic semaphores
633 Semaphores have two methods, "down()" and "up()": "down()" decrements
634 the resource count, while "up()" increments it. Calls to "down()" will
635 block if the semaphore's current count would decrement below zero.
636 This program gives a quick demonstration:
637 use threads;
639 use Thread::Semaphore;
640 my $semaphore = Thread::Semaphore->new();
642 my $GlobalVariable :shared = 0;
643 $thr1 = threads->create(\&sample_sub, 1);
645 $thr2 = threads->create(\&sample_sub, 2);
646 $thr3 = threads->create(\&sample_sub, 3);
647 sub sample_sub {
649 my $SubNumber = shift(@_);
650 my $TryCount = 10;
651 my $LocalCopy;
652 sleep(1);
653 while ($TryCount--) {
654 $semaphore->down();
655 $LocalCopy = $GlobalVariable;
656 print("$TryCount tries left for sub $SubNumber (\$GlobalVariable is $GlobalVariable)\n");
657 sleep(2);
658 $LocalCopy++;
659 $GlobalVariable = $LocalCopy;
660 $semaphore->up();
661 }
662 }
663 $thr1->join();
665 $thr2->join();
666 $thr3->join();
667 The three invocations of the subroutine all operate in sync. The
669 semaphore, though, makes sure that only one thread is accessing the
670 global variable at once.
671 Advanced Semaphores
673 By default, semaphores behave like locks, letting only one thread
674 "down()" them at a time. However, there are other uses for semaphores.
675 Each semaphore has a counter attached to it. By default, semaphores are
677 created with the counter set to one, "down()" decrements the counter by
678 one, and "up()" increments by one. However, we can override any or all
679 of these defaults simply by passing in different values:
680 use threads;
682 use Thread::Semaphore;
683 my $semaphore = Thread::Semaphore->new(5);
685 # Creates a semaphore with the counter set to five
686 my $thr1 = threads->create(\&sub1);
688 my $thr2 = threads->create(\&sub1);
689 sub sub1 {
691 $semaphore->down(5); # Decrements the counter by five
692 # Do stuff here
693 $semaphore->up(5); # Increment the counter by five
694 }
695 $thr1->detach();
697 $thr2->detach();
698 If "down()" attempts to decrement the counter below zero, it blocks
700 until the counter is large enough. Note that while a semaphore can be
701 created with a starting count of zero, any "up()" or "down()" always
702 changes the counter by at least one, and so "$semaphore->down(0)" is
703 the same as "$semaphore->down(1)".
704 The question, of course, is why would you do something like this? Why
706 create a semaphore with a starting count that's not one, or why
707 decrement or increment it by more than one? The answer is resource
708 availability. Many resources that you want to manage access for can be
709 safely used by more than one thread at once.
710 For example, let's take a GUI driven program. It has a semaphore that
712 it uses to synchronize access to the display, so only one thread is
713 ever drawing at once. Handy, but of course you don't want any thread
714 to start drawing until things are properly set up. In this case, you
715 can create a semaphore with a counter set to zero, and up it when
716 things are ready for drawing.
717 Semaphores with counters greater than one are also useful for
719 establishing quotas. Say, for example, that you have a number of
720 threads that can do I/O at once. You don't want all the threads
721 reading or writing at once though, since that can potentially swamp
722 your I/O channels, or deplete your process' quota of filehandles. You
723 can use a semaphore initialized to the number of concurrent I/O
724 requests (or open files) that you want at any one time, and have your
725 threads quietly block and unblock themselves.
726 Larger increments or decrements are handy in those cases where a thread
728 needs to check out or return a number of resources at once.
729 Waiting for a Condition
731 The functions "cond_wait()" and "cond_signal()" can be used in
732 conjunction with locks to notify co-operating threads that a resource
733 has become available. They are very similar in use to the functions
734 found in "pthreads". However for most purposes, queues are simpler to
735 use and more intuitive. See threads::shared for more details.
736 Giving up control
738 There are times when you may find it useful to have a thread explicitly
739 give up the CPU to another thread. You may be doing something
740 processor-intensive and want to make sure that the user-interface
741 thread gets called frequently. Regardless, there are times that you
742 might want a thread to give up the processor.
743 Perl's threading package provides the "yield()" function that does
745 this. "yield()" is pretty straightforward, and works like this:
746 use threads;
748 sub loop {
750 my $thread = shift;
751 my $foo = 50;
752 while($foo--) { print("In thread $thread\n"); }
753 threads->yield();
754 $foo = 50;
755 while($foo--) { print("In thread $thread\n"); }
756 }
757 my $thr1 = threads->create(\&loop, 'first');
759 my $thr2 = threads->create(\&loop, 'second');
760 my $thr3 = threads->create(\&loop, 'third');
761 It is important to remember that "yield()" is only a hint to give up
763 the CPU, it depends on your hardware, OS and threading libraries what
764 actually happens. On many operating systems, yield() is a no-op.
765 Therefore it is important to note that one should not build the
766 scheduling of the threads around "yield()" calls. It might work on your
767 platform but it won't work on another platform.
768
770 We've covered the workhorse parts of Perl's threading package, and with
771 these tools you should be well on your way to writing threaded code and
772 packages. There are a few useful little pieces that didn't really fit
773 in anyplace else.
774 What Thread Am I In?
776 The "threads->self()" class method provides your program with a way to
777 get an object representing the thread it's currently in. You can use
778 this object in the same way as the ones returned from thread creation.
779 Thread IDs
781 "tid()" is a thread object method that returns the thread ID of the
782 thread the object represents. Thread IDs are integers, with the main
783 thread in a program being 0. Currently Perl assigns a unique TID to
784 every thread ever created in your program, assigning the first thread
785 to be created a TID of 1, and increasing the TID by 1 for each new
786 thread that's created. When used as a class method, "threads->tid()"
787 can be used by a thread to get its own TID.
788 Are These Threads The Same?
790 The "equal()" method takes two thread objects and returns true if the
791 objects represent the same thread, and false if they don't.
792 Thread objects also have an overloaded "==" comparison so that you can
794 do comparison on them as you would with normal objects.
795 What Threads Are Running?
797 "threads->list()" returns a list of thread objects, one for each thread
798 that's currently running and not detached. Handy for a number of
799 things, including cleaning up at the end of your program (from the main
800 Perl thread, of course):
801 # Loop through all the threads
803 foreach my $thr (threads->list()) {
804 $thr->join();
805 }
806 If some threads have not finished running when the main Perl thread
808 ends, Perl will warn you about it and die, since it is impossible for
809 Perl to clean up itself while other threads are running.
810 NOTE: The main Perl thread (thread 0) is in a detached state, and so
812 does not appear in the list returned by "threads->list()".
813
815 Confused yet? It's time for an example program to show some of the
816 things we've covered. This program finds prime numbers using threads.
817 1 #!/usr/bin/perl
819 2 # prime-pthread, courtesy of Tom Christiansen
820 3
821 4 use strict;
822 5 use warnings;
823 6
824 7 use threads;
825 8 use Thread::Queue;
826 9
827 10 sub check_num {
828 11 my ($upstream, $cur_prime) = @_;
829 12 my $kid;
830 13 my $downstream = Thread::Queue->new();
831 14 while (my $num = $upstream->dequeue()) {
832 15 next unless ($num % $cur_prime);
833 16 if ($kid) {
834 17 $downstream->enqueue($num);
835 18 } else {
836 19 print("Found prime: $num\n");
837 20 $kid = threads->create(\&check_num, $downstream, $num);
838 21 if (! $kid) {
839 22 warn("Sorry. Ran out of threads.\n");
840 23 last;
841 24 }
842 25 }
843 26 }
844 27 if ($kid) {
845 28 $downstream->enqueue(undef);
846 29 $kid->join();
847 30 }
848 31 }
849 32
850 33 my $stream = Thread::Queue->new(3..1000, undef);
851 34 check_num($stream, 2);
852 This program uses the pipeline model to generate prime numbers. Each
854 thread in the pipeline has an input queue that feeds numbers to be
855 checked, a prime number that it's responsible for, and an output queue
856 into which it funnels numbers that have failed the check. If the
857 thread has a number that's failed its check and there's no child
858 thread, then the thread must have found a new prime number. In that
859 case, a new child thread is created for that prime and stuck on the end
860 of the pipeline.
861 This probably sounds a bit more confusing than it really is, so let's
863 go through this program piece by piece and see what it does. (For
864 those of you who might be trying to remember exactly what a prime
865 number is, it's a number that's only evenly divisible by itself and 1.)
866 The bulk of the work is done by the "check_num()" subroutine, which
868 takes a reference to its input queue and a prime number that it's
869 responsible for. After pulling in the input queue and the prime that
870 the subroutine is checking (line 11), we create a new queue (line 13)
871 and reserve a scalar for the thread that we're likely to create later
872 (line 12).
873 The while loop from line 14 to line 26 grabs a scalar off the input
875 queue and checks against the prime this thread is responsible for.
876 Line 15 checks to see if there's a remainder when we divide the number
877 to be checked by our prime. If there is one, the number must not be
878 evenly divisible by our prime, so we need to either pass it on to the
879 next thread if we've created one (line 17) or create a new thread if we
880 haven't.
881 The new thread creation is line 20. We pass on to it a reference to
883 the queue we've created, and the prime number we've found. In lines 21
884 through 24, we check to make sure that our new thread got created, and
885 if not, we stop checking any remaining numbers in the queue.
886 Finally, once the loop terminates (because we got a 0 or "undef" in the
888 queue, which serves as a note to terminate), we pass on the notice to
889 our child, and wait for it to exit if we've created a child (lines 27
890 and 30).
891 Meanwhile, back in the main thread, we first create a queue (line 33)
893 and queue up all the numbers from 3 to 1000 for checking, plus a
894 termination notice. Then all we have to do to get the ball rolling is
895 pass the queue and the first prime to the "check_num()" subroutine
896 (line 34).
897 That's how it works. It's pretty simple; as with many Perl programs,
899 the explanation is much longer than the program.
900
902 Some background on thread implementations from the operating system
903 viewpoint. There are three basic categories of threads: user-mode
904 threads, kernel threads, and multiprocessor kernel threads.
905 User-mode threads are threads that live entirely within a program and
907 its libraries. In this model, the OS knows nothing about threads. As
908 far as it's concerned, your process is just a process.
909 This is the easiest way to implement threads, and the way most OSes
911 start. The big disadvantage is that, since the OS knows nothing about
912 threads, if one thread blocks they all do. Typical blocking activities
913 include most system calls, most I/O, and things like "sleep()".
914 Kernel threads are the next step in thread evolution. The OS knows
916 about kernel threads, and makes allowances for them. The main
917 difference between a kernel thread and a user-mode thread is blocking.
918 With kernel threads, things that block a single thread don't block
919 other threads. This is not the case with user-mode threads, where the
920 kernel blocks at the process level and not the thread level.
921 This is a big step forward, and can give a threaded program quite a
923 performance boost over non-threaded programs. Threads that block
924 performing I/O, for example, won't block threads that are doing other
925 things. Each process still has only one thread running at once,
926 though, regardless of how many CPUs a system might have.
927 Since kernel threading can interrupt a thread at any time, they will
929 uncover some of the implicit locking assumptions you may make in your
930 program. For example, something as simple as "$a = $a + 2" can behave
931 unpredictably with kernel threads if $a is visible to other threads, as
932 another thread may have changed $a between the time it was fetched on
933 the right hand side and the time the new value is stored.
934 Multiprocessor kernel threads are the final step in thread support.
936 With multiprocessor kernel threads on a machine with multiple CPUs, the
937 OS may schedule two or more threads to run simultaneously on different
938 CPUs.
939 This can give a serious performance boost to your threaded program,
941 since more than one thread will be executing at the same time. As a
942 tradeoff, though, any of those nagging synchronization issues that
943 might not have shown with basic kernel threads will appear with a
944 vengeance.
945 In addition to the different levels of OS involvement in threads,
947 different OSes (and different thread implementations for a particular
948 OS) allocate CPU cycles to threads in different ways.
949 Cooperative multitasking systems have running threads give up control
951 if one of two things happen. If a thread calls a yield function, it
952 gives up control. It also gives up control if the thread does
953 something that would cause it to block, such as perform I/O. In a
954 cooperative multitasking implementation, one thread can starve all the
955 others for CPU time if it so chooses.
956 Preemptive multitasking systems interrupt threads at regular intervals
958 while the system decides which thread should run next. In a preemptive
959 multitasking system, one thread usually won't monopolize the CPU.
960 On some systems, there can be cooperative and preemptive threads
962 running simultaneously. (Threads running with realtime priorities often
963 behave cooperatively, for example, while threads running at normal
964 priorities behave preemptively.)
965 Most modern operating systems support preemptive multitasking nowadays.
967
969 The main thing to bear in mind when comparing Perl's ithreads to other
970 threading models is the fact that for each new thread created, a
971 complete copy of all the variables and data of the parent thread has to
972 be taken. Thus, thread creation can be quite expensive, both in terms
973 of memory usage and time spent in creation. The ideal way to reduce
974 these costs is to have a relatively short number of long-lived threads,
975 all created fairly early on -- before the base thread has accumulated
976 too much data. Of course, this may not always be possible, so
977 compromises have to be made. However, after a thread has been created,
978 its performance and extra memory usage should be little different than
979 ordinary code.
980 Also note that under the current implementation, shared variables use a
982 little more memory and are a little slower than ordinary variables.
983
985 Note that while threads themselves are separate execution threads and
986 Perl data is thread-private unless explicitly shared, the threads can
987 affect process-scope state, affecting all the threads.
988 The most common example of this is changing the current working
990 directory using "chdir()". One thread calls "chdir()", and the working
991 directory of all the threads changes.
992 Even more drastic example of a process-scope change is "chroot()": the
994 root directory of all the threads changes, and no thread can undo it
995 (as opposed to "chdir()").
996 Further examples of process-scope changes include "umask()" and
998 changing uids and gids.
999 Thinking of mixing "fork()" and threads? Please lie down and wait
1001 until the feeling passes. Be aware that the semantics of "fork()" vary
1002 between platforms. For example, some UNIX systems copy all the current
1003 threads into the child process, while others only copy the thread that
1004 called "fork()". You have been warned!
1005 Similarly, mixing signals and threads may be problematic.
1007 Implementations are platform-dependent, and even the POSIX semantics
1008 may not be what you expect (and Perl doesn't even give you the full
1009 POSIX API). For example, there is no way to guarantee that a signal
1010 sent to a multi-threaded Perl application will get intercepted by any
1011 particular thread. (However, a recently added feature does provide the
1012 capability to send signals between threads. See ""THREAD SIGNALLING"
1013 in threads for more details.)
1014
1016 Whether various library calls are thread-safe is outside the control of
1017 Perl. Calls often suffering from not being thread-safe include:
1018 "localtime()", "gmtime()", functions fetching user, group and network
1019 information (such as "getgrent()", "gethostent()", "getnetent()" and so
1020 on), "readdir()", "rand()", and "srand()" -- in general, calls that
1021 depend on some global external state.
1022 If the system Perl is compiled in has thread-safe variants of such
1024 calls, they will be used. Beyond that, Perl is at the mercy of the
1025 thread-safety or -unsafety of the calls. Please consult your C library
1026 call documentation.
1027 On some platforms the thread-safe library interfaces may fail if the
1029 result buffer is too small (for example the user group databases may be
1030 rather large, and the reentrant interfaces may have to carry around a
1031 full snapshot of those databases). Perl will start with a small
1032 buffer, but keep retrying and growing the result buffer until the
1033 result fits. If this limitless growing sounds bad for security or
1034 memory consumption reasons you can recompile Perl with
1035 "PERL_REENTRANT_MAXSIZE" defined to the maximum number of bytes you
1036 will allow.
1037
1039 A complete thread tutorial could fill a book (and has, many times), but
1040 with what we've covered in this introduction, you should be well on
1041 your way to becoming a threaded Perl expert.
1042
1044 Annotated POD for threads:
1045 <http://annocpan.org/?mode=search&field=Module&name=threads>
1046 Lastest version of threads on CPAN:
1048 <http://search.cpan.org/search?module=threads>
1049 Annotated POD for threads::shared:
1051 <http://annocpan.org/?mode=search&field=Module&name=threads%3A%3Ashared>
1052 Lastest version of threads::shared on CPAN:
1054 <http://search.cpan.org/search?module=threads%3A%3Ashared>
1055 Perl threads mailing list:
1057 <http://lists.cpan.org/showlist.cgi?name=iThreads>
1058
1060 Here's a short bibliography courtesy of JA~Xrgen Christoffel:
1061 Introductory Texts
1063 Birrell, Andrew D. An Introduction to Programming with Threads. Digital
1064 Equipment Corporation, 1989, DEC-SRC Research Report #35 online as
1065 http://gatekeeper.dec.com/pub/DEC/SRC/research-reports/abstracts/src-rr-035.html
1066 (highly recommended)
1067 Robbins, Kay. A., and Steven Robbins. Practical Unix Programming: A
1069 Guide to Concurrency, Communication, and Multithreading. Prentice-Hall,
1070 1996.
1071 Lewis, Bill, and Daniel J. Berg. Multithreaded Programming with
1073 Pthreads. Prentice Hall, 1997, ISBN 0-13-443698-9 (a well-written
1074 introduction to threads).
1075 Nelson, Greg (editor). Systems Programming with Modula-3. Prentice
1077 Hall, 1991, ISBN 0-13-590464-1.
1078 Nichols, Bradford, Dick Buttlar, and Jacqueline Proulx Farrell.
1080 Pthreads Programming. O'Reilly & Associates, 1996, ISBN 156592-115-1
1081 (covers POSIX threads).
1082 OS-Related References
1084 Boykin, Joseph, David Kirschen, Alan Langerman, and Susan LoVerso.
1085 Programming under Mach. Addison-Wesley, 1994, ISBN 0-201-52739-1.
1086 Tanenbaum, Andrew S. Distributed Operating Systems. Prentice Hall,
1088 1995, ISBN 0-13-219908-4 (great textbook).
1089 Silberschatz, Abraham, and Peter B. Galvin. Operating System Concepts,
1091 4th ed. Addison-Wesley, 1995, ISBN 0-201-59292-4
1092 Other References
1094 Arnold, Ken and James Gosling. The Java Programming Language, 2nd ed.
1095 Addison-Wesley, 1998, ISBN 0-201-31006-6.
1096 comp.programming.threads FAQ,
1098 <http://www.serpentine.com/~bos/threads-faq/>
1099 Le Sergent, T. and B. Berthomieu. "Incremental MultiThreaded Garbage
1101 Collection on Virtually Shared Memory Architectures" in Memory
1102 Management: Proc. of the International Workshop IWMM 92, St. Malo,
1103 France, September 1992, Yves Bekkers and Jacques Cohen, eds. Springer,
1104 1992, ISBN 3540-55940-X (real-life thread applications).
1105 Artur Bergman, "Where Wizards Fear To Tread", June 11, 2002,
1107 <http://www.perl.com/pub/a/2002/06/11/threads.html>
1108
1110 Thanks (in no particular order) to Chaim Frenkel, Steve Fink, Gurusamy
1111 Sarathy, Ilya Zakharevich, Benjamin Sugars, JA~Xrgen Christoffel,
1112 Joshua Pritikin, and Alan Burlison, for their help in reality-checking
1113 and polishing this article. Big thanks to Tom Christiansen for his
1114 rewrite of the prime number generator.
1115
1117 Dan Sugalski <dan@sidhe.org<gt>
1118 Slightly modified by Arthur Bergman to fit the new thread model/module.
1120 Reworked slightly by JA~Xrg Walter <jwalt@cpan.org<gt> to be more
1122 concise about thread-safety of Perl code.
1123 Rearranged slightly by Elizabeth Mattijsen <liz@dijkmat.nl<gt> to put
1125 less emphasis on yield().
1126
1128 The original version of this article originally appeared in The Perl
1129 Journal #10, and is copyright 1998 The Perl Journal. It appears
1130 courtesy of Jon Orwant and The Perl Journal. This document may be
1131 distributed under the same terms as Perl itself.
1132perl v5.10.1 2009-04-14 PERLTHRTUT(1)