Commit | Line | Data |
---|---|---|
86530b38 AT |
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 Thread-Safe 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 perl data is | |
210 | not shared among threads by default, Perl modules stand a high chance of | |
211 | being thread-safe or can be made thread-safe easily. Modules that are not | |
212 | tagged as thread-safe should be tested or code reviewed before being used | |
213 | in production code. | |
214 | ||
215 | Not all modules that you might use are thread-safe, and you should | |
216 | always assume a module is unsafe unless the documentation says | |
217 | otherwise. This includes modules that are distributed as part of the | |
218 | core. Threads are a new feature, and even some of the standard | |
219 | modules aren't thread-safe. | |
220 | ||
221 | Even if a module is thread-safe, it doesn't mean that the module is optimized | |
222 | to work well with threads. A module could possibly be rewritten to utilize | |
223 | the new features in threaded Perl to increase performance in a threaded | |
224 | environment. | |
225 | ||
226 | If you're using a module that's not thread-safe for some reason, you | |
227 | can protect yourself by using it from one, and only one thread at all. | |
228 | If you need multiple threads to access such a module, you can use semaphores and | |
229 | lots of programming discipline to control access to it. Semaphores | |
230 | are covered in L</"Basic semaphores">. | |
231 | ||
232 | See also L</"Thread-Safety of System Libraries">. | |
233 | ||
234 | =head1 Thread Basics | |
235 | ||
236 | The core L<threads> module provides the basic functions you need to write | |
237 | threaded programs. In the following sections we'll cover the basics, | |
238 | showing you what you need to do to create a threaded program. After | |
239 | that, we'll go over some of the features of the L<threads> module that | |
240 | make threaded programming easier. | |
241 | ||
242 | =head2 Basic Thread Support | |
243 | ||
244 | Thread support is a Perl compile-time option - it's something that's | |
245 | turned on or off when Perl is built at your site, rather than when | |
246 | your programs are compiled. If your Perl wasn't compiled with thread | |
247 | support enabled, then any attempt to use threads will fail. | |
248 | ||
249 | Your programs can use the Config module to check whether threads are | |
250 | enabled. If your program can't run without them, you can say something | |
251 | like: | |
252 | ||
253 | $Config{useithreads} or die "Recompile Perl with threads to run this program."; | |
254 | ||
255 | A possibly-threaded program using a possibly-threaded module might | |
256 | have code like this: | |
257 | ||
258 | use Config; | |
259 | use MyMod; | |
260 | ||
261 | BEGIN { | |
262 | if ($Config{useithreads}) { | |
263 | # We have threads | |
264 | require MyMod_threaded; | |
265 | import MyMod_threaded; | |
266 | } else { | |
267 | require MyMod_unthreaded; | |
268 | import MyMod_unthreaded; | |
269 | } | |
270 | } | |
271 | ||
272 | Since code that runs both with and without threads is usually pretty | |
273 | messy, it's best to isolate the thread-specific code in its own | |
274 | module. In our example above, that's what MyMod_threaded is, and it's | |
275 | only imported if we're running on a threaded Perl. | |
276 | ||
277 | =head2 A Note about the Examples | |
278 | ||
279 | Although thread support is considered to be stable, there are still a number | |
280 | of quirks that may startle you when you try out any of the examples below. | |
281 | In a real situation, care should be taken that all threads are finished | |
282 | executing before the program exits. That care has B<not> been taken in these | |
283 | examples in the interest of simplicity. Running these examples "as is" will | |
284 | produce error messages, usually caused by the fact that there are still | |
285 | threads running when the program exits. You should not be alarmed by this. | |
286 | Future versions of Perl may fix this problem. | |
287 | ||
288 | =head2 Creating Threads | |
289 | ||
290 | The L<threads> package provides the tools you need to create new | |
291 | threads. Like any other module, you need to tell Perl that you want to use | |
292 | it; C<use threads> imports all the pieces you need to create basic | |
293 | threads. | |
294 | ||
295 | The simplest, most straightforward way to create a thread is with new(): | |
296 | ||
297 | use threads; | |
298 | ||
299 | $thr = threads->new(\&sub1); | |
300 | ||
301 | sub sub1 { | |
302 | print "In the thread\n"; | |
303 | } | |
304 | ||
305 | The new() method takes a reference to a subroutine and creates a new | |
306 | thread, which starts executing in the referenced subroutine. Control | |
307 | then passes both to the subroutine and the caller. | |
308 | ||
309 | If you need to, your program can pass parameters to the subroutine as | |
310 | part of the thread startup. Just include the list of parameters as | |
311 | part of the C<threads::new> call, like this: | |
312 | ||
313 | use threads; | |
314 | ||
315 | $Param3 = "foo"; | |
316 | $thr = threads->new(\&sub1, "Param 1", "Param 2", $Param3); | |
317 | $thr = threads->new(\&sub1, @ParamList); | |
318 | $thr = threads->new(\&sub1, qw(Param1 Param2 Param3)); | |
319 | ||
320 | sub sub1 { | |
321 | my @InboundParameters = @_; | |
322 | print "In the thread\n"; | |
323 | print "got parameters >", join("<>", @InboundParameters), "<\n"; | |
324 | } | |
325 | ||
326 | ||
327 | The last example illustrates another feature of threads. You can spawn | |
328 | off several threads using the same subroutine. Each thread executes | |
329 | the same subroutine, but in a separate thread with a separate | |
330 | environment and potentially separate arguments. | |
331 | ||
332 | C<create()> is a synonym for C<new()>. | |
333 | ||
334 | =head2 Giving up control | |
335 | ||
336 | There are times when you may find it useful to have a thread | |
337 | explicitly give up the CPU to another thread. Your threading package | |
338 | might not support preemptive multitasking for threads, for example, or | |
339 | you may be doing something processor-intensive and want to make sure | |
340 | that the user-interface thread gets called frequently. Regardless, | |
341 | there are times that you might want a thread to give up the processor. | |
342 | ||
343 | Perl's threading package provides the yield() function that does | |
344 | this. yield() is pretty straightforward, and works like this: | |
345 | ||
346 | use threads; | |
347 | ||
348 | sub loop { | |
349 | my $thread = shift; | |
350 | my $foo = 50; | |
351 | while($foo--) { print "in thread $thread\n" } | |
352 | threads->yield; | |
353 | $foo = 50; | |
354 | while($foo--) { print "in thread $thread\n" } | |
355 | } | |
356 | ||
357 | my $thread1 = threads->new(\&loop, 'first'); | |
358 | my $thread2 = threads->new(\&loop, 'second'); | |
359 | my $thread3 = threads->new(\&loop, 'third'); | |
360 | ||
361 | It is important to remember that yield() is only a hint to give up the CPU, | |
362 | it depends on your hardware, OS and threading libraries what actually happens. | |
363 | Therefore it is important to note that one should not build the scheduling of | |
364 | the threads around yield() calls. It might work on your platform but it won't | |
365 | work on another platform. | |
366 | ||
367 | =head2 Waiting For A Thread To Exit | |
368 | ||
369 | Since threads are also subroutines, they can return values. To wait | |
370 | for a thread to exit and extract any values it might return, you can | |
371 | use the join() method: | |
372 | ||
373 | use threads; | |
374 | ||
375 | $thr = threads->new(\&sub1); | |
376 | ||
377 | @ReturnData = $thr->join; | |
378 | print "Thread returned @ReturnData"; | |
379 | ||
380 | sub sub1 { return "Fifty-six", "foo", 2; } | |
381 | ||
382 | In the example above, the join() method returns as soon as the thread | |
383 | ends. In addition to waiting for a thread to finish and gathering up | |
384 | any values that the thread might have returned, join() also performs | |
385 | any OS cleanup necessary for the thread. That cleanup might be | |
386 | important, especially for long-running programs that spawn lots of | |
387 | threads. If you don't want the return values and don't want to wait | |
388 | for the thread to finish, you should call the detach() method | |
389 | instead, as described next. | |
390 | ||
391 | =head2 Ignoring A Thread | |
392 | ||
393 | join() does three things: it waits for a thread to exit, cleans up | |
394 | after it, and returns any data the thread may have produced. But what | |
395 | if you're not interested in the thread's return values, and you don't | |
396 | really care when the thread finishes? All you want is for the thread | |
397 | to get cleaned up after when it's done. | |
398 | ||
399 | In this case, you use the detach() method. Once a thread is detached, | |
400 | it'll run until it's finished, then Perl will clean up after it | |
401 | automatically. | |
402 | ||
403 | use threads; | |
404 | ||
405 | $thr = threads->new(\&sub1); # Spawn the thread | |
406 | ||
407 | $thr->detach; # Now we officially don't care any more | |
408 | ||
409 | sub sub1 { | |
410 | $a = 0; | |
411 | while (1) { | |
412 | $a++; | |
413 | print "\$a is $a\n"; | |
414 | sleep 1; | |
415 | } | |
416 | } | |
417 | ||
418 | Once a thread is detached, it may not be joined, and any return data | |
419 | that it might have produced (if it was done and waiting for a join) is | |
420 | lost. | |
421 | ||
422 | =head1 Threads And Data | |
423 | ||
424 | Now that we've covered the basics of threads, it's time for our next | |
425 | topic: data. Threading introduces a couple of complications to data | |
426 | access that non-threaded programs never need to worry about. | |
427 | ||
428 | =head2 Shared And Unshared Data | |
429 | ||
430 | The biggest difference between Perl ithreads and the old 5.005 style | |
431 | threading, or for that matter, to most other threading systems out there, | |
432 | is that by default, no data is shared. When a new perl thread is created, | |
433 | all the data associated with the current thread is copied to the new | |
434 | thread, and is subsequently private to that new thread! | |
435 | This is similar in feel to what happens when a UNIX process forks, | |
436 | except that in this case, the data is just copied to a different part of | |
437 | memory within the same process rather than a real fork taking place. | |
438 | ||
439 | To make use of threading however, one usually wants the threads to share | |
440 | at least some data between themselves. This is done with the | |
441 | L<threads::shared> module and the C< : shared> attribute: | |
442 | ||
443 | use threads; | |
444 | use threads::shared; | |
445 | ||
446 | my $foo : shared = 1; | |
447 | my $bar = 1; | |
448 | threads->new(sub { $foo++; $bar++ })->join; | |
449 | ||
450 | print "$foo\n"; #prints 2 since $foo is shared | |
451 | print "$bar\n"; #prints 1 since $bar is not shared | |
452 | ||
453 | In the case of a shared array, all the array's elements are shared, and for | |
454 | a shared hash, all the keys and values are shared. This places | |
455 | restrictions on what may be assigned to shared array and hash elements: only | |
456 | simple values or references to shared variables are allowed - this is | |
457 | so that a private variable can't accidentally become shared. A bad | |
458 | assignment will cause the thread to die. For example: | |
459 | ||
460 | use threads; | |
461 | use threads::shared; | |
462 | ||
463 | my $var = 1; | |
464 | my $svar : shared = 2; | |
465 | my %hash : shared; | |
466 | ||
467 | ... create some threads ... | |
468 | ||
469 | $hash{a} = 1; # all threads see exists($hash{a}) and $hash{a} == 1 | |
470 | $hash{a} = $var # okay - copy-by-value: same effect as previous | |
471 | $hash{a} = $svar # okay - copy-by-value: same effect as previous | |
472 | $hash{a} = \$svar # okay - a reference to a shared variable | |
473 | $hash{a} = \$var # This will die | |
474 | delete $hash{a} # okay - all threads will see !exists($hash{a}) | |
475 | ||
476 | Note that a shared variable guarantees that if two or more threads try to | |
477 | modify it at the same time, the internal state of the variable will not | |
478 | become corrupted. However, there are no guarantees beyond this, as | |
479 | explained in the next section. | |
480 | ||
481 | =head2 Thread Pitfalls: Races | |
482 | ||
483 | While threads bring a new set of useful tools, they also bring a | |
484 | number of pitfalls. One pitfall is the race condition: | |
485 | ||
486 | use threads; | |
487 | use threads::shared; | |
488 | ||
489 | my $a : shared = 1; | |
490 | $thr1 = threads->new(\&sub1); | |
491 | $thr2 = threads->new(\&sub2); | |
492 | ||
493 | $thr1->join; | |
494 | $thr2->join; | |
495 | print "$a\n"; | |
496 | ||
497 | sub sub1 { my $foo = $a; $a = $foo + 1; } | |
498 | sub sub2 { my $bar = $a; $a = $bar + 1; } | |
499 | ||
500 | What do you think $a will be? The answer, unfortunately, is "it | |
501 | depends." Both sub1() and sub2() access the global variable $a, once | |
502 | to read and once to write. Depending on factors ranging from your | |
503 | thread implementation's scheduling algorithm to the phase of the moon, | |
504 | $a can be 2 or 3. | |
505 | ||
506 | Race conditions are caused by unsynchronized access to shared | |
507 | data. Without explicit synchronization, there's no way to be sure that | |
508 | nothing has happened to the shared data between the time you access it | |
509 | and the time you update it. Even this simple code fragment has the | |
510 | possibility of error: | |
511 | ||
512 | use threads; | |
513 | my $a : shared = 2; | |
514 | my $b : shared; | |
515 | my $c : shared; | |
516 | my $thr1 = threads->create(sub { $b = $a; $a = $b + 1; }); | |
517 | my $thr2 = threads->create(sub { $c = $a; $a = $c + 1; }); | |
518 | $thr1->join; | |
519 | $thr2->join; | |
520 | ||
521 | Two threads both access $a. Each thread can potentially be interrupted | |
522 | at any point, or be executed in any order. At the end, $a could be 3 | |
523 | or 4, and both $b and $c could be 2 or 3. | |
524 | ||
525 | Even C<$a += 5> or C<$a++> are not guaranteed to be atomic. | |
526 | ||
527 | Whenever your program accesses data or resources that can be accessed | |
528 | by other threads, you must take steps to coordinate access or risk | |
529 | data inconsistency and race conditions. Note that Perl will protect its | |
530 | internals from your race conditions, but it won't protect you from you. | |
531 | ||
532 | =head1 Synchronization and control | |
533 | ||
534 | Perl provides a number of mechanisms to coordinate the interactions | |
535 | between themselves and their data, to avoid race conditions and the like. | |
536 | Some of these are designed to resemble the common techniques used in thread | |
537 | libraries such as C<pthreads>; others are Perl-specific. Often, the | |
538 | standard techniques are clumsy and difficult to get right (such as | |
539 | condition waits). Where possible, it is usually easier to use Perlish | |
540 | techniques such as queues, which remove some of the hard work involved. | |
541 | ||
542 | =head2 Controlling access: lock() | |
543 | ||
544 | The lock() function takes a shared variable and puts a lock on it. | |
545 | No other thread may lock the variable until the the variable is unlocked | |
546 | by the thread holding the lock. Unlocking happens automatically | |
547 | when the locking thread exits the outermost block that contains | |
548 | C<lock()> function. Using lock() is straightforward: this example has | |
549 | several threads doing some calculations in parallel, and occasionally | |
550 | updating a running total: | |
551 | ||
552 | use threads; | |
553 | use threads::shared; | |
554 | ||
555 | my $total : shared = 0; | |
556 | ||
557 | sub calc { | |
558 | for (;;) { | |
559 | my $result; | |
560 | # (... do some calculations and set $result ...) | |
561 | { | |
562 | lock($total); # block until we obtain the lock | |
563 | $total += $result; | |
564 | } # lock implicitly released at end of scope | |
565 | last if $result == 0; | |
566 | } | |
567 | } | |
568 | ||
569 | my $thr1 = threads->new(\&calc); | |
570 | my $thr2 = threads->new(\&calc); | |
571 | my $thr3 = threads->new(\&calc); | |
572 | $thr1->join; | |
573 | $thr2->join; | |
574 | $thr3->join; | |
575 | print "total=$total\n"; | |
576 | ||
577 | ||
578 | lock() blocks the thread until the variable being locked is | |
579 | available. When lock() returns, your thread can be sure that no other | |
580 | thread can lock that variable until the outermost block containing the | |
581 | lock exits. | |
582 | ||
583 | It's important to note that locks don't prevent access to the variable | |
584 | in question, only lock attempts. This is in keeping with Perl's | |
585 | longstanding tradition of courteous programming, and the advisory file | |
586 | locking that flock() gives you. | |
587 | ||
588 | You may lock arrays and hashes as well as scalars. Locking an array, | |
589 | though, will not block subsequent locks on array elements, just lock | |
590 | attempts on the array itself. | |
591 | ||
592 | Locks are recursive, which means it's okay for a thread to | |
593 | lock a variable more than once. The lock will last until the outermost | |
594 | lock() on the variable goes out of scope. For example: | |
595 | ||
596 | my $x : shared; | |
597 | doit(); | |
598 | ||
599 | sub doit { | |
600 | { | |
601 | { | |
602 | lock($x); # wait for lock | |
603 | lock($x); # NOOP - we already have the lock | |
604 | { | |
605 | lock($x); # NOOP | |
606 | { | |
607 | lock($x); # NOOP | |
608 | lockit_some_more(); | |
609 | } | |
610 | } | |
611 | } # *** implicit unlock here *** | |
612 | } | |
613 | } | |
614 | ||
615 | sub lockit_some_more { | |
616 | lock($x); # NOOP | |
617 | } # nothing happens here | |
618 | ||
619 | Note that there is no unlock() function - the only way to unlock a | |
620 | variable is to allow it to go out of scope. | |
621 | ||
622 | A lock can either be used to guard the data contained within the variable | |
623 | being locked, or it can be used to guard something else, like a section | |
624 | of code. In this latter case, the variable in question does not hold any | |
625 | useful data, and exists only for the purpose of being locked. In this | |
626 | respect, the variable behaves like the mutexes and basic semaphores of | |
627 | traditional thread libraries. | |
628 | ||
629 | =head2 A Thread Pitfall: Deadlocks | |
630 | ||
631 | Locks are a handy tool to synchronize access to data, and using them | |
632 | properly is the key to safe shared data. Unfortunately, locks aren't | |
633 | without their dangers, especially when multiple locks are involved. | |
634 | Consider the following code: | |
635 | ||
636 | use threads; | |
637 | ||
638 | my $a : shared = 4; | |
639 | my $b : shared = "foo"; | |
640 | my $thr1 = threads->new(sub { | |
641 | lock($a); | |
642 | threads->yield; | |
643 | sleep 20; | |
644 | lock($b); | |
645 | }); | |
646 | my $thr2 = threads->new(sub { | |
647 | lock($b); | |
648 | threads->yield; | |
649 | sleep 20; | |
650 | lock($a); | |
651 | }); | |
652 | ||
653 | This program will probably hang until you kill it. The only way it | |
654 | won't hang is if one of the two threads acquires both locks | |
655 | first. A guaranteed-to-hang version is more complicated, but the | |
656 | principle is the same. | |
657 | ||
658 | The first thread will grab a lock on $a, then, after a pause during which | |
659 | the second thread has probably had time to do some work, try to grab a | |
660 | lock on $b. Meanwhile, the second thread grabs a lock on $b, then later | |
661 | tries to grab a lock on $a. The second lock attempt for both threads will | |
662 | block, each waiting for the other to release its lock. | |
663 | ||
664 | This condition is called a deadlock, and it occurs whenever two or | |
665 | more threads are trying to get locks on resources that the others | |
666 | own. Each thread will block, waiting for the other to release a lock | |
667 | on a resource. That never happens, though, since the thread with the | |
668 | resource is itself waiting for a lock to be released. | |
669 | ||
670 | There are a number of ways to handle this sort of problem. The best | |
671 | way is to always have all threads acquire locks in the exact same | |
672 | order. If, for example, you lock variables $a, $b, and $c, always lock | |
673 | $a before $b, and $b before $c. It's also best to hold on to locks for | |
674 | as short a period of time to minimize the risks of deadlock. | |
675 | ||
676 | The other synchronization primitives described below can suffer from | |
677 | similar problems. | |
678 | ||
679 | =head2 Queues: Passing Data Around | |
680 | ||
681 | A queue is a special thread-safe object that lets you put data in one | |
682 | end and take it out the other without having to worry about | |
683 | synchronization issues. They're pretty straightforward, and look like | |
684 | this: | |
685 | ||
686 | use threads; | |
687 | use Thread::Queue; | |
688 | ||
689 | my $DataQueue = Thread::Queue->new; | |
690 | $thr = threads->new(sub { | |
691 | while ($DataElement = $DataQueue->dequeue) { | |
692 | print "Popped $DataElement off the queue\n"; | |
693 | } | |
694 | }); | |
695 | ||
696 | $DataQueue->enqueue(12); | |
697 | $DataQueue->enqueue("A", "B", "C"); | |
698 | $DataQueue->enqueue(\$thr); | |
699 | sleep 10; | |
700 | $DataQueue->enqueue(undef); | |
701 | $thr->join; | |
702 | ||
703 | You create the queue with C<new Thread::Queue>. Then you can | |
704 | add lists of scalars onto the end with enqueue(), and pop scalars off | |
705 | the front of it with dequeue(). A queue has no fixed size, and can grow | |
706 | as needed to hold everything pushed on to it. | |
707 | ||
708 | If a queue is empty, dequeue() blocks until another thread enqueues | |
709 | something. This makes queues ideal for event loops and other | |
710 | communications between threads. | |
711 | ||
712 | =head2 Semaphores: Synchronizing Data Access | |
713 | ||
714 | Semaphores are a kind of generic locking mechanism. In their most basic | |
715 | form, they behave very much like lockable scalars, except that thay | |
716 | can't hold data, and that they must be explicitly unlocked. In their | |
717 | advanced form, they act like a kind of counter, and can allow multiple | |
718 | threads to have the 'lock' at any one time. | |
719 | ||
720 | =head2 Basic semaphores | |
721 | ||
722 | Semaphores have two methods, down() and up(): down() decrements the resource | |
723 | count, while up increments it. Calls to down() will block if the | |
724 | semaphore's current count would decrement below zero. This program | |
725 | gives a quick demonstration: | |
726 | ||
727 | use threads qw(yield); | |
728 | use Thread::Semaphore; | |
729 | ||
730 | my $semaphore = new Thread::Semaphore; | |
731 | my $GlobalVariable : shared = 0; | |
732 | ||
733 | $thr1 = new threads \&sample_sub, 1; | |
734 | $thr2 = new threads \&sample_sub, 2; | |
735 | $thr3 = new threads \&sample_sub, 3; | |
736 | ||
737 | sub sample_sub { | |
738 | my $SubNumber = shift @_; | |
739 | my $TryCount = 10; | |
740 | my $LocalCopy; | |
741 | sleep 1; | |
742 | while ($TryCount--) { | |
743 | $semaphore->down; | |
744 | $LocalCopy = $GlobalVariable; | |
745 | print "$TryCount tries left for sub $SubNumber (\$GlobalVariable is $GlobalVariable)\n"; | |
746 | yield; | |
747 | sleep 2; | |
748 | $LocalCopy++; | |
749 | $GlobalVariable = $LocalCopy; | |
750 | $semaphore->up; | |
751 | } | |
752 | } | |
753 | ||
754 | $thr1->join; | |
755 | $thr2->join; | |
756 | $thr3->join; | |
757 | ||
758 | The three invocations of the subroutine all operate in sync. The | |
759 | semaphore, though, makes sure that only one thread is accessing the | |
760 | global variable at once. | |
761 | ||
762 | =head2 Advanced Semaphores | |
763 | ||
764 | By default, semaphores behave like locks, letting only one thread | |
765 | down() them at a time. However, there are other uses for semaphores. | |
766 | ||
767 | Each semaphore has a counter attached to it. By default, semaphores are | |
768 | created with the counter set to one, down() decrements the counter by | |
769 | one, and up() increments by one. However, we can override any or all | |
770 | of these defaults simply by passing in different values: | |
771 | ||
772 | use threads; | |
773 | use Thread::Semaphore; | |
774 | my $semaphore = Thread::Semaphore->new(5); | |
775 | # Creates a semaphore with the counter set to five | |
776 | ||
777 | $thr1 = threads->new(\&sub1); | |
778 | $thr2 = threads->new(\&sub1); | |
779 | ||
780 | sub sub1 { | |
781 | $semaphore->down(5); # Decrements the counter by five | |
782 | # Do stuff here | |
783 | $semaphore->up(5); # Increment the counter by five | |
784 | } | |
785 | ||
786 | $thr1->detach; | |
787 | $thr2->detach; | |
788 | ||
789 | If down() attempts to decrement the counter below zero, it blocks until | |
790 | the counter is large enough. Note that while a semaphore can be created | |
791 | with a starting count of zero, any up() or down() always changes the | |
792 | counter by at least one, and so $semaphore->down(0) is the same as | |
793 | $semaphore->down(1). | |
794 | ||
795 | The question, of course, is why would you do something like this? Why | |
796 | create a semaphore with a starting count that's not one, or why | |
797 | decrement/increment it by more than one? The answer is resource | |
798 | availability. Many resources that you want to manage access for can be | |
799 | safely used by more than one thread at once. | |
800 | ||
801 | For example, let's take a GUI driven program. It has a semaphore that | |
802 | it uses to synchronize access to the display, so only one thread is | |
803 | ever drawing at once. Handy, but of course you don't want any thread | |
804 | to start drawing until things are properly set up. In this case, you | |
805 | can create a semaphore with a counter set to zero, and up it when | |
806 | things are ready for drawing. | |
807 | ||
808 | Semaphores with counters greater than one are also useful for | |
809 | establishing quotas. Say, for example, that you have a number of | |
810 | threads that can do I/O at once. You don't want all the threads | |
811 | reading or writing at once though, since that can potentially swamp | |
812 | your I/O channels, or deplete your process' quota of filehandles. You | |
813 | can use a semaphore initialized to the number of concurrent I/O | |
814 | requests (or open files) that you want at any one time, and have your | |
815 | threads quietly block and unblock themselves. | |
816 | ||
817 | Larger increments or decrements are handy in those cases where a | |
818 | thread needs to check out or return a number of resources at once. | |
819 | ||
820 | =head2 cond_wait() and cond_signal() | |
821 | ||
822 | These two functions can be used in conjunction with locks to notify | |
823 | co-operating threads that a resource has become available. They are | |
824 | very similar in use to the functions found in C<pthreads>. However | |
825 | for most purposes, queues are simpler to use and more intuitive. See | |
826 | L<threads::shared> for more details. | |
827 | ||
828 | =head1 General Thread Utility Routines | |
829 | ||
830 | We've covered the workhorse parts of Perl's threading package, and | |
831 | with these tools you should be well on your way to writing threaded | |
832 | code and packages. There are a few useful little pieces that didn't | |
833 | really fit in anyplace else. | |
834 | ||
835 | =head2 What Thread Am I In? | |
836 | ||
837 | The C<< threads->self >> class method provides your program with a way to | |
838 | get an object representing the thread it's currently in. You can use this | |
839 | object in the same way as the ones returned from thread creation. | |
840 | ||
841 | =head2 Thread IDs | |
842 | ||
843 | tid() is a thread object method that returns the thread ID of the | |
844 | thread the object represents. Thread IDs are integers, with the main | |
845 | thread in a program being 0. Currently Perl assigns a unique tid to | |
846 | every thread ever created in your program, assigning the first thread | |
847 | to be created a tid of 1, and increasing the tid by 1 for each new | |
848 | thread that's created. | |
849 | ||
850 | =head2 Are These Threads The Same? | |
851 | ||
852 | The equal() method takes two thread objects and returns true | |
853 | if the objects represent the same thread, and false if they don't. | |
854 | ||
855 | Thread objects also have an overloaded == comparison so that you can do | |
856 | comparison on them as you would with normal objects. | |
857 | ||
858 | =head2 What Threads Are Running? | |
859 | ||
860 | C<< threads->list >> returns a list of thread objects, one for each thread | |
861 | that's currently running and not detached. Handy for a number of things, | |
862 | including cleaning up at the end of your program: | |
863 | ||
864 | # Loop through all the threads | |
865 | foreach $thr (threads->list) { | |
866 | # Don't join the main thread or ourselves | |
867 | if ($thr->tid && !threads::equal($thr, threads->self)) { | |
868 | $thr->join; | |
869 | } | |
870 | } | |
871 | ||
872 | If some threads have not finished running when the main Perl thread | |
873 | ends, Perl will warn you about it and die, since it is impossible for Perl | |
874 | to clean up itself while other threads are running | |
875 | ||
876 | =head1 A Complete Example | |
877 | ||
878 | Confused yet? It's time for an example program to show some of the | |
879 | things we've covered. This program finds prime numbers using threads. | |
880 | ||
881 | 1 #!/usr/bin/perl -w | |
882 | 2 # prime-pthread, courtesy of Tom Christiansen | |
883 | 3 | |
884 | 4 use strict; | |
885 | 5 | |
886 | 6 use threads; | |
887 | 7 use Thread::Queue; | |
888 | 8 | |
889 | 9 my $stream = new Thread::Queue; | |
890 | 10 my $kid = new threads(\&check_num, $stream, 2); | |
891 | 11 | |
892 | 12 for my $i ( 3 .. 1000 ) { | |
893 | 13 $stream->enqueue($i); | |
894 | 14 } | |
895 | 15 | |
896 | 16 $stream->enqueue(undef); | |
897 | 17 $kid->join; | |
898 | 18 | |
899 | 19 sub check_num { | |
900 | 20 my ($upstream, $cur_prime) = @_; | |
901 | 21 my $kid; | |
902 | 22 my $downstream = new Thread::Queue; | |
903 | 23 while (my $num = $upstream->dequeue) { | |
904 | 24 next unless $num % $cur_prime; | |
905 | 25 if ($kid) { | |
906 | 26 $downstream->enqueue($num); | |
907 | 27 } else { | |
908 | 28 print "Found prime $num\n"; | |
909 | 29 $kid = new threads(\&check_num, $downstream, $num); | |
910 | 30 } | |
911 | 31 } | |
912 | 32 $downstream->enqueue(undef) if $kid; | |
913 | 33 $kid->join if $kid; | |
914 | 34 } | |
915 | ||
916 | This program uses the pipeline model to generate prime numbers. Each | |
917 | thread in the pipeline has an input queue that feeds numbers to be | |
918 | checked, a prime number that it's responsible for, and an output queue | |
919 | into which it funnels numbers that have failed the check. If the thread | |
920 | has a number that's failed its check and there's no child thread, then | |
921 | the thread must have found a new prime number. In that case, a new | |
922 | child thread is created for that prime and stuck on the end of the | |
923 | pipeline. | |
924 | ||
925 | This probably sounds a bit more confusing than it really is, so let's | |
926 | go through this program piece by piece and see what it does. (For | |
927 | those of you who might be trying to remember exactly what a prime | |
928 | number is, it's a number that's only evenly divisible by itself and 1) | |
929 | ||
930 | The bulk of the work is done by the check_num() subroutine, which | |
931 | takes a reference to its input queue and a prime number that it's | |
932 | responsible for. After pulling in the input queue and the prime that | |
933 | the subroutine's checking (line 20), we create a new queue (line 22) | |
934 | and reserve a scalar for the thread that we're likely to create later | |
935 | (line 21). | |
936 | ||
937 | The while loop from lines 23 to line 31 grabs a scalar off the input | |
938 | queue and checks against the prime this thread is responsible | |
939 | for. Line 24 checks to see if there's a remainder when we modulo the | |
940 | number to be checked against our prime. If there is one, the number | |
941 | must not be evenly divisible by our prime, so we need to either pass | |
942 | it on to the next thread if we've created one (line 26) or create a | |
943 | new thread if we haven't. | |
944 | ||
945 | The new thread creation is line 29. We pass on to it a reference to | |
946 | the queue we've created, and the prime number we've found. | |
947 | ||
948 | Finally, once the loop terminates (because we got a 0 or undef in the | |
949 | queue, which serves as a note to die), we pass on the notice to our | |
950 | child and wait for it to exit if we've created a child (lines 32 and | |
951 | 37). | |
952 | ||
953 | Meanwhile, back in the main thread, we create a queue (line 9) and the | |
954 | initial child thread (line 10), and pre-seed it with the first prime: | |
955 | 2. Then we queue all the numbers from 3 to 1000 for checking (lines | |
956 | 12-14), then queue a die notice (line 16) and wait for the first child | |
957 | thread to terminate (line 17). Because a child won't die until its | |
958 | child has died, we know that we're done once we return from the join. | |
959 | ||
960 | That's how it works. It's pretty simple; as with many Perl programs, | |
961 | the explanation is much longer than the program. | |
962 | ||
963 | =head1 Performance considerations | |
964 | ||
965 | The main thing to bear in mind when comparing ithreads to other threading | |
966 | models is the fact that for each new thread created, a complete copy of | |
967 | all the variables and data of the parent thread has to be taken. Thus | |
968 | thread creation can be quite expensive, both in terms of memory usage and | |
969 | time spent in creation. The ideal way to reduce these costs is to have a | |
970 | relatively short number of long-lived threads, all created fairly early | |
971 | on - before the base thread has accumulated too much data. Of course, this | |
972 | may not always be possible, so compromises have to be made. However, after | |
973 | a thread has been created, its performance and extra memory usage should | |
974 | be little different than ordinary code. | |
975 | ||
976 | Also note that under the current implementation, shared variables | |
977 | use a little more memory and are a little slower than ordinary variables. | |
978 | ||
979 | =head1 Process-scope Changes | |
980 | ||
981 | Note that while threads themselves are separate execution threads and | |
982 | Perl data is thread-private unless explicitly shared, the threads can | |
983 | affect process-scope state, affecting all the threads. | |
984 | ||
985 | The most common example of this is changing the current working | |
986 | directory using chdir(). One thread calls chdir(), and the working | |
987 | directory of all the threads changes. | |
988 | ||
989 | Even more drastic example of a process-scope change is chroot(): | |
990 | the root directory of all the threads changes, and no thread can | |
991 | undo it (as opposed to chdir()). | |
992 | ||
993 | Further examples of process-scope changes include umask() and | |
994 | changing uids/gids. | |
995 | ||
996 | Thinking of mixing fork() and threads? Please lie down and wait | |
997 | until the feeling passes-- but in case you really want to know, | |
998 | the semantics is that fork() duplicates all the threads. | |
999 | (In UNIX, at least, other platforms will do something different.) | |
1000 | ||
1001 | Similarly, mixing signals and threads should not be attempted. | |
1002 | Implementations are platform-dependent, and even the POSIX | |
1003 | semantics may not be what you expect (and Perl doesn't even | |
1004 | give you the full POSIX API). | |
1005 | ||
1006 | =head1 Thread-Safety of System Libraries | |
1007 | ||
1008 | Whether various library calls are thread-safe is outside the control | |
1009 | of Perl. Calls often suffering from not being thread-safe include: | |
1010 | localtime(), gmtime(), get{gr,host,net,proto,serv,pw}*(), readdir(), | |
1011 | rand(), and srand() -- in general, calls that depend on some global | |
1012 | external state. | |
1013 | ||
1014 | If the system Perl is compiled in has thread-safe variants of such | |
1015 | calls, they will be used. Beyond that, Perl is at the mercy of | |
1016 | the thread-safety or -unsafety of the calls. Please consult your | |
1017 | C library call documentation. | |
1018 | ||
1019 | In some platforms the thread-safe interfaces may fail if the result | |
1020 | buffer is too small (for example getgrent() may return quite large | |
1021 | group member lists). Perl will retry growing the result buffer | |
1022 | a few times, but only up to 64k (for safety reasons). | |
1023 | ||
1024 | =head1 Conclusion | |
1025 | ||
1026 | A complete thread tutorial could fill a book (and has, many times), | |
1027 | but with what we've covered in this introduction, you should be well | |
1028 | on your way to becoming a threaded Perl expert. | |
1029 | ||
1030 | =head1 Bibliography | |
1031 | ||
1032 |