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