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