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