diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/perlthrtut.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/perlthrtut.1 | 1232 |
1 files changed, 1232 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/perlthrtut.1 b/upstream/mageia-cauldron/man1/perlthrtut.1 new file mode 100644 index 00000000..507c70c4 --- /dev/null +++ b/upstream/mageia-cauldron/man1/perlthrtut.1 @@ -0,0 +1,1232 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "PERLTHRTUT 1" +.TH PERLTHRTUT 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +perlthrtut \- Tutorial on threads in Perl +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This tutorial describes the use of Perl interpreter threads (sometimes +referred to as \fIithreads\fR). In this +model, each thread runs in its own Perl interpreter, and any data sharing +between threads must be explicit. The user-level interface for \fIithreads\fR +uses the threads class. +.PP +\&\fBNOTE\fR: There was another older Perl threading flavor called the 5.005 model +that used the threads class. This old model was known to have problems, is +deprecated, and was removed for release 5.10. You are +strongly encouraged to migrate any existing 5.005 threads code to the new +model as soon as possible. +.PP +You can see which (or neither) threading flavour you have by +running \f(CW\*(C`perl \-V\*(C'\fR and looking at the \f(CW\*(C`Platform\*(C'\fR section. +If you have \f(CW\*(C`useithreads=define\*(C'\fR you have ithreads, if you +have \f(CW\*(C`use5005threads=define\*(C'\fR you have 5.005 threads. +If you have neither, you don't have any thread support built in. +If you have both, you are in trouble. +.PP +The threads and threads::shared modules are included in the core Perl +distribution. Additionally, they are maintained as a separate modules on +CPAN, so you can check there for any updates. +.SH "What Is A Thread Anyway?" +.IX Header "What Is A Thread Anyway?" +A thread is a flow of control through a program with a single +execution point. +.PP +Sounds an awful lot like a process, doesn't it? Well, it should. +Threads are one of the pieces of a process. Every process has at least +one thread and, up until now, every process running Perl had only one +thread. With 5.8, though, you can create extra threads. We're going +to show you how, when, and why. +.SH "Threaded Program Models" +.IX Header "Threaded Program Models" +There are three basic ways that you can structure a threaded +program. Which model you choose depends on what you need your program +to do. For many non-trivial threaded programs, you'll need to choose +different models for different pieces of your program. +.SS Boss/Worker +.IX Subsection "Boss/Worker" +The boss/worker model usually has one \fIboss\fR thread and one or more +\&\fIworker\fR threads. The boss thread gathers or generates tasks that need +to be done, then parcels those tasks out to the appropriate worker +thread. +.PP +This model is common in GUI and server programs, where a main thread +waits for some event and then passes that event to the appropriate +worker threads for processing. Once the event has been passed on, the +boss thread goes back to waiting for another event. +.PP +The boss thread does relatively little work. While tasks aren't +necessarily performed faster than with any other method, it tends to +have the best user-response times. +.SS "Work Crew" +.IX Subsection "Work Crew" +In the work crew model, several threads are created that do +essentially the same thing to different pieces of data. It closely +mirrors classical parallel processing and vector processors, where a +large array of processors do the exact same thing to many pieces of +data. +.PP +This model is particularly useful if the system running the program +will distribute multiple threads across different processors. It can +also be useful in ray tracing or rendering engines, where the +individual threads can pass on interim results to give the user visual +feedback. +.SS Pipeline +.IX Subsection "Pipeline" +The pipeline model divides up a task into a series of steps, and +passes the results of one step on to the thread processing the +next. Each thread does one thing to each piece of data and passes the +results to the next thread in line. +.PP +This model makes the most sense if you have multiple processors so two +or more threads will be executing in parallel, though it can often +make sense in other contexts as well. It tends to keep the individual +tasks small and simple, as well as allowing some parts of the pipeline +to block (on I/O or system calls, for example) while other parts keep +going. If you're running different parts of the pipeline on different +processors you may also take advantage of the caches on each +processor. +.PP +This model is also handy for a form of recursive programming where, +rather than having a subroutine call itself, it instead creates +another thread. Prime and Fibonacci generators both map well to this +form of the pipeline model. (A version of a prime number generator is +presented later on.) +.SH "What kind of threads are Perl threads?" +.IX Header "What kind of threads are Perl threads?" +If you have experience with other thread implementations, you might +find that things aren't quite what you expect. It's very important to +remember when dealing with Perl threads that \fIPerl Threads Are Not X +Threads\fR for all values of X. They aren't POSIX threads, or +DecThreads, or Java's Green threads, or Win32 threads. There are +similarities, and the broad concepts are the same, but if you start +looking for implementation details you're going to be either +disappointed or confused. Possibly both. +.PP +This is not to say that Perl threads are completely different from +everything that's ever come before. They're not. Perl's threading +model owes a lot to other thread models, especially POSIX. Just as +Perl is not C, though, Perl threads are not POSIX threads. So if you +find yourself looking for mutexes, or thread priorities, it's time to +step back a bit and think about what you want to do and how Perl can +do it. +.PP +However, it is important to remember that Perl threads cannot magically +do things unless your operating system's threads allow it. So if your +system blocks the entire process on \f(CWsleep()\fR, Perl usually will, as well. +.PP +\&\fBPerl Threads Are Different.\fR +.SH "Thread-Safe Modules" +.IX Header "Thread-Safe Modules" +The addition of threads has changed Perl's internals +substantially. There are implications for people who write +modules with XS code or external libraries. However, since Perl data is +not shared among threads by default, Perl modules stand a high chance of +being thread-safe or can be made thread-safe easily. Modules that are not +tagged as thread-safe should be tested or code reviewed before being used +in production code. +.PP +Not all modules that you might use are thread-safe, and you should +always assume a module is unsafe unless the documentation says +otherwise. This includes modules that are distributed as part of the +core. Threads are a relatively new feature, and even some of the standard +modules aren't thread-safe. +.PP +Even if a module is thread-safe, it doesn't mean that the module is optimized +to work well with threads. A module could possibly be rewritten to utilize +the new features in threaded Perl to increase performance in a threaded +environment. +.PP +If you're using a module that's not thread-safe for some reason, you +can protect yourself by using it from one, and only one thread at all. +If you need multiple threads to access such a module, you can use semaphores and +lots of programming discipline to control access to it. Semaphores +are covered in "Basic semaphores". +.PP +See also "Thread-Safety of System Libraries". +.SH "Thread Basics" +.IX Header "Thread Basics" +The threads module provides the basic functions you need to write +threaded programs. In the following sections, we'll cover the basics, +showing you what you need to do to create a threaded program. After +that, we'll go over some of the features of the threads module that +make threaded programming easier. +.SS "Basic Thread Support" +.IX Subsection "Basic Thread Support" +Thread support is a Perl compile-time option. It's something that's +turned on or off when Perl is built at your site, rather than when +your programs are compiled. If your Perl wasn't compiled with thread +support enabled, then any attempt to use threads will fail. +.PP +Your programs can use the Config module to check whether threads are +enabled. If your program can't run without them, you can say something +like: +.PP +.Vb 3 +\& use Config; +\& $Config{useithreads} or +\& die(\*(AqRecompile Perl with threads to run this program.\*(Aq); +.Ve +.PP +A possibly-threaded program using a possibly-threaded module might +have code like this: +.PP +.Vb 2 +\& use Config; +\& use MyMod; +\& +\& BEGIN { +\& if ($Config{useithreads}) { +\& # We have threads +\& require MyMod_threaded; +\& import MyMod_threaded; +\& } else { +\& require MyMod_unthreaded; +\& import MyMod_unthreaded; +\& } +\& } +.Ve +.PP +Since code that runs both with and without threads is usually pretty +messy, it's best to isolate the thread-specific code in its own +module. In our example above, that's what \f(CW\*(C`MyMod_threaded\*(C'\fR is, and it's +only imported if we're running on a threaded Perl. +.SS "A Note about the Examples" +.IX Subsection "A Note about the Examples" +In a real situation, care should be taken that all threads are finished +executing before the program exits. That care has \fBnot\fR been taken in these +examples in the interest of simplicity. Running these examples \fIas is\fR will +produce error messages, usually caused by the fact that there are still +threads running when the program exits. You should not be alarmed by this. +.SS "Creating Threads" +.IX Subsection "Creating Threads" +The threads module provides the tools you need to create new +threads. Like any other module, you need to tell Perl that you want to use +it; \f(CW\*(C`use threads;\*(C'\fR imports all the pieces you need to create basic +threads. +.PP +The simplest, most straightforward way to create a thread is with \f(CWcreate()\fR: +.PP +.Vb 1 +\& use threads; +\& +\& my $thr = threads\->create(\e&sub1); +\& +\& sub sub1 { +\& print("In the thread\en"); +\& } +.Ve +.PP +The \f(CWcreate()\fR method takes a reference to a subroutine and creates a new +thread that starts executing in the referenced subroutine. Control +then passes both to the subroutine and the caller. +.PP +If you need to, your program can pass parameters to the subroutine as +part of the thread startup. Just include the list of parameters as +part of the \f(CW\*(C`threads\->create()\*(C'\fR call, like this: +.PP +.Vb 1 +\& use threads; +\& +\& my $Param3 = \*(Aqfoo\*(Aq; +\& my $thr1 = threads\->create(\e&sub1, \*(AqParam 1\*(Aq, \*(AqParam 2\*(Aq, $Param3); +\& my @ParamList = (42, \*(AqHello\*(Aq, 3.14); +\& my $thr2 = threads\->create(\e&sub1, @ParamList); +\& my $thr3 = threads\->create(\e&sub1, qw(Param1 Param2 Param3)); +\& +\& sub sub1 { +\& my @InboundParameters = @_; +\& print("In the thread\en"); +\& print(\*(AqGot parameters >\*(Aq, join(\*(Aq<>\*(Aq,@InboundParameters), "<\en"); +\& } +.Ve +.PP +The last example illustrates another feature of threads. You can spawn +off several threads using the same subroutine. Each thread executes +the same subroutine, but in a separate thread with a separate +environment and potentially separate arguments. +.PP +\&\f(CWnew()\fR is a synonym for \f(CWcreate()\fR. +.SS "Waiting For A Thread To Exit" +.IX Subsection "Waiting For A Thread To Exit" +Since threads are also subroutines, they can return values. To wait +for a thread to exit and extract any values it might return, you can +use the \f(CWjoin()\fR method: +.PP +.Vb 1 +\& use threads; +\& +\& my ($thr) = threads\->create(\e&sub1); +\& +\& my @ReturnData = $thr\->join(); +\& print(\*(AqThread returned \*(Aq, join(\*(Aq, \*(Aq, @ReturnData), "\en"); +\& +\& sub sub1 { return (\*(AqFifty\-six\*(Aq, \*(Aqfoo\*(Aq, 2); } +.Ve +.PP +In the example above, the \f(CWjoin()\fR method returns as soon as the thread +ends. In addition to waiting for a thread to finish and gathering up +any values that the thread might have returned, \f(CWjoin()\fR also performs +any OS cleanup necessary for the thread. That cleanup might be +important, especially for long-running programs that spawn lots of +threads. If you don't want the return values and don't want to wait +for the thread to finish, you should call the \f(CWdetach()\fR method +instead, as described next. +.PP +NOTE: In the example above, the thread returns a list, thus necessitating +that the thread creation call be made in list context (i.e., \f(CW\*(C`my ($thr)\*(C'\fR). +See "$thr\->\fBjoin()\fR" in threads and "THREAD CONTEXT" in threads for more +details on thread context and return values. +.SS "Ignoring A Thread" +.IX Subsection "Ignoring A Thread" +\&\f(CWjoin()\fR does three things: it waits for a thread to exit, cleans up +after it, and returns any data the thread may have produced. But what +if you're not interested in the thread's return values, and you don't +really care when the thread finishes? All you want is for the thread +to get cleaned up after when it's done. +.PP +In this case, you use the \f(CWdetach()\fR method. Once a thread is detached, +it'll run until it's finished; then Perl will clean up after it +automatically. +.PP +.Vb 1 +\& use threads; +\& +\& my $thr = threads\->create(\e&sub1); # Spawn the thread +\& +\& $thr\->detach(); # Now we officially don\*(Aqt care any more +\& +\& sleep(15); # Let thread run for awhile +\& +\& sub sub1 { +\& my $count = 0; +\& while (1) { +\& $count++; +\& print("\e$count is $count\en"); +\& sleep(1); +\& } +\& } +.Ve +.PP +Once a thread is detached, it may not be joined, and any return data +that it might have produced (if it was done and waiting for a join) is +lost. +.PP +\&\f(CWdetach()\fR can also be called as a class method to allow a thread to +detach itself: +.PP +.Vb 1 +\& use threads; +\& +\& my $thr = threads\->create(\e&sub1); +\& +\& sub sub1 { +\& threads\->detach(); +\& # Do more work +\& } +.Ve +.SS "Process and Thread Termination" +.IX Subsection "Process and Thread Termination" +With threads one must be careful to make sure they all have a chance to +run to completion, assuming that is what you want. +.PP +An action that terminates a process will terminate \fIall\fR running +threads. \fBdie()\fR and \fBexit()\fR have this property, +and perl does an exit when the main thread exits, +perhaps implicitly by falling off the end of your code, +even if that's not what you want. +.PP +As an example of this case, this code prints the message +"Perl exited with active threads: 2 running and unjoined": +.PP +.Vb 8 +\& use threads; +\& my $thr1 = threads\->new(\e&thrsub, "test1"); +\& my $thr2 = threads\->new(\e&thrsub, "test2"); +\& sub thrsub { +\& my ($message) = @_; +\& sleep 1; +\& print "thread $message\en"; +\& } +.Ve +.PP +But when the following lines are added at the end: +.PP +.Vb 2 +\& $thr1\->join(); +\& $thr2\->join(); +.Ve +.PP +it prints two lines of output, a perhaps more useful outcome. +.SH "Threads And Data" +.IX Header "Threads And Data" +Now that we've covered the basics of threads, it's time for our next +topic: Data. Threading introduces a couple of complications to data +access that non-threaded programs never need to worry about. +.SS "Shared And Unshared Data" +.IX Subsection "Shared And Unshared Data" +The biggest difference between Perl \fIithreads\fR and the old 5.005 style +threading, or for that matter, to most other threading systems out there, +is that by default, no data is shared. When a new Perl thread is created, +all the data associated with the current thread is copied to the new +thread, and is subsequently private to that new thread! +This is similar in feel to what happens when a Unix process forks, +except that in this case, the data is just copied to a different part of +memory within the same process rather than a real fork taking place. +.PP +To make use of threading, however, one usually wants the threads to share +at least some data between themselves. This is done with the +threads::shared module and the \f(CW\*(C`:shared\*(C'\fR attribute: +.PP +.Vb 2 +\& use threads; +\& use threads::shared; +\& +\& my $foo :shared = 1; +\& my $bar = 1; +\& threads\->create(sub { $foo++; $bar++; })\->join(); +\& +\& print("$foo\en"); # Prints 2 since $foo is shared +\& print("$bar\en"); # Prints 1 since $bar is not shared +.Ve +.PP +In the case of a shared array, all the array's elements are shared, and for +a shared hash, all the keys and values are shared. This places +restrictions on what may be assigned to shared array and hash elements: only +simple values or references to shared variables are allowed \- this is +so that a private variable can't accidentally become shared. A bad +assignment will cause the thread to die. For example: +.PP +.Vb 2 +\& use threads; +\& use threads::shared; +\& +\& my $var = 1; +\& my $svar :shared = 2; +\& my %hash :shared; +\& +\& ... create some threads ... +\& +\& $hash{a} = 1; # All threads see exists($hash{a}) +\& # and $hash{a} == 1 +\& $hash{a} = $var; # okay \- copy\-by\-value: same effect as previous +\& $hash{a} = $svar; # okay \- copy\-by\-value: same effect as previous +\& $hash{a} = \e$svar; # okay \- a reference to a shared variable +\& $hash{a} = \e$var; # This will die +\& delete($hash{a}); # okay \- all threads will see !exists($hash{a}) +.Ve +.PP +Note that a shared variable guarantees that if two or more threads try to +modify it at the same time, the internal state of the variable will not +become corrupted. However, there are no guarantees beyond this, as +explained in the next section. +.SS "Thread Pitfalls: Races" +.IX Subsection "Thread Pitfalls: Races" +While threads bring a new set of useful tools, they also bring a +number of pitfalls. One pitfall is the race condition: +.PP +.Vb 2 +\& use threads; +\& use threads::shared; +\& +\& my $x :shared = 1; +\& my $thr1 = threads\->create(\e&sub1); +\& my $thr2 = threads\->create(\e&sub2); +\& +\& $thr1\->join(); +\& $thr2\->join(); +\& print("$x\en"); +\& +\& sub sub1 { my $foo = $x; $x = $foo + 1; } +\& sub sub2 { my $bar = $x; $x = $bar + 1; } +.Ve +.PP +What do you think \f(CW$x\fR will be? The answer, unfortunately, is \fIit +depends\fR. Both \f(CWsub1()\fR and \f(CWsub2()\fR access the global variable \f(CW$x\fR, once +to read and once to write. Depending on factors ranging from your +thread implementation's scheduling algorithm to the phase of the moon, +\&\f(CW$x\fR can be 2 or 3. +.PP +Race conditions are caused by unsynchronized access to shared +data. Without explicit synchronization, there's no way to be sure that +nothing has happened to the shared data between the time you access it +and the time you update it. Even this simple code fragment has the +possibility of error: +.PP +.Vb 8 +\& use threads; +\& my $x :shared = 2; +\& my $y :shared; +\& my $z :shared; +\& my $thr1 = threads\->create(sub { $y = $x; $x = $y + 1; }); +\& my $thr2 = threads\->create(sub { $z = $x; $x = $z + 1; }); +\& $thr1\->join(); +\& $thr2\->join(); +.Ve +.PP +Two threads both access \f(CW$x\fR. Each thread can potentially be interrupted +at any point, or be executed in any order. At the end, \f(CW$x\fR could be 3 +or 4, and both \f(CW$y\fR and \f(CW$z\fR could be 2 or 3. +.PP +Even \f(CW\*(C`$x += 5\*(C'\fR or \f(CW\*(C`$x++\*(C'\fR are not guaranteed to be atomic. +.PP +Whenever your program accesses data or resources that can be accessed +by other threads, you must take steps to coordinate access or risk +data inconsistency and race conditions. Note that Perl will protect its +internals from your race conditions, but it won't protect you from you. +.SH "Synchronization and control" +.IX Header "Synchronization and control" +Perl provides a number of mechanisms to coordinate the interactions +between themselves and their data, to avoid race conditions and the like. +Some of these are designed to resemble the common techniques used in thread +libraries such as \f(CW\*(C`pthreads\*(C'\fR; others are Perl-specific. Often, the +standard techniques are clumsy and difficult to get right (such as +condition waits). Where possible, it is usually easier to use Perlish +techniques such as queues, which remove some of the hard work involved. +.SS "Controlling access: \fBlock()\fP" +.IX Subsection "Controlling access: lock()" +The \f(CWlock()\fR function takes a shared variable and puts a lock on it. +No other thread may lock the variable until the variable is unlocked +by the thread holding the lock. Unlocking happens automatically +when the locking thread exits the block that contains the call to the +\&\f(CWlock()\fR function. Using \f(CWlock()\fR is straightforward: This example has +several threads doing some calculations in parallel, and occasionally +updating a running total: +.PP +.Vb 2 +\& use threads; +\& use threads::shared; +\& +\& my $total :shared = 0; +\& +\& sub calc { +\& while (1) { +\& my $result; +\& # (... do some calculations and set $result ...) +\& { +\& lock($total); # Block until we obtain the lock +\& $total += $result; +\& } # Lock implicitly released at end of scope +\& last if $result == 0; +\& } +\& } +\& +\& my $thr1 = threads\->create(\e&calc); +\& my $thr2 = threads\->create(\e&calc); +\& my $thr3 = threads\->create(\e&calc); +\& $thr1\->join(); +\& $thr2\->join(); +\& $thr3\->join(); +\& print("total=$total\en"); +.Ve +.PP +\&\f(CWlock()\fR blocks the thread until the variable being locked is +available. When \f(CWlock()\fR returns, your thread can be sure that no other +thread can lock that variable until the block containing the +lock exits. +.PP +It's important to note that locks don't prevent access to the variable +in question, only lock attempts. This is in keeping with Perl's +longstanding tradition of courteous programming, and the advisory file +locking that \f(CWflock()\fR gives you. +.PP +You may lock arrays and hashes as well as scalars. Locking an array, +though, will not block subsequent locks on array elements, just lock +attempts on the array itself. +.PP +Locks are recursive, which means it's okay for a thread to +lock a variable more than once. The lock will last until the outermost +\&\f(CWlock()\fR on the variable goes out of scope. For example: +.PP +.Vb 2 +\& my $x :shared; +\& doit(); +\& +\& sub doit { +\& { +\& { +\& lock($x); # Wait for lock +\& lock($x); # NOOP \- we already have the lock +\& { +\& lock($x); # NOOP +\& { +\& lock($x); # NOOP +\& lockit_some_more(); +\& } +\& } +\& } # *** Implicit unlock here *** +\& } +\& } +\& +\& sub lockit_some_more { +\& lock($x); # NOOP +\& } # Nothing happens here +.Ve +.PP +Note that there is no \f(CWunlock()\fR function \- the only way to unlock a +variable is to allow it to go out of scope. +.PP +A lock can either be used to guard the data contained within the variable +being locked, or it can be used to guard something else, like a section +of code. In this latter case, the variable in question does not hold any +useful data, and exists only for the purpose of being locked. In this +respect, the variable behaves like the mutexes and basic semaphores of +traditional thread libraries. +.SS "A Thread Pitfall: Deadlocks" +.IX Subsection "A Thread Pitfall: Deadlocks" +Locks are a handy tool to synchronize access to data, and using them +properly is the key to safe shared data. Unfortunately, locks aren't +without their dangers, especially when multiple locks are involved. +Consider the following code: +.PP +.Vb 1 +\& use threads; +\& +\& my $x :shared = 4; +\& my $y :shared = \*(Aqfoo\*(Aq; +\& my $thr1 = threads\->create(sub { +\& lock($x); +\& sleep(20); +\& lock($y); +\& }); +\& my $thr2 = threads\->create(sub { +\& lock($y); +\& sleep(20); +\& lock($x); +\& }); +.Ve +.PP +This program will probably hang until you kill it. The only way it +won't hang is if one of the two threads acquires both locks +first. A guaranteed-to-hang version is more complicated, but the +principle is the same. +.PP +The first thread will grab a lock on \f(CW$x\fR, then, after a pause during which +the second thread has probably had time to do some work, try to grab a +lock on \f(CW$y\fR. Meanwhile, the second thread grabs a lock on \f(CW$y\fR, then later +tries to grab a lock on \f(CW$x\fR. The second lock attempt for both threads will +block, each waiting for the other to release its lock. +.PP +This condition is called a deadlock, and it occurs whenever two or +more threads are trying to get locks on resources that the others +own. Each thread will block, waiting for the other to release a lock +on a resource. That never happens, though, since the thread with the +resource is itself waiting for a lock to be released. +.PP +There are a number of ways to handle this sort of problem. The best +way is to always have all threads acquire locks in the exact same +order. If, for example, you lock variables \f(CW$x\fR, \f(CW$y\fR, and \f(CW$z\fR, always lock +\&\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 +as short a period of time to minimize the risks of deadlock. +.PP +The other synchronization primitives described below can suffer from +similar problems. +.SS "Queues: Passing Data Around" +.IX Subsection "Queues: Passing Data Around" +A queue is a special thread-safe object that lets you put data in one +end and take it out the other without having to worry about +synchronization issues. They're pretty straightforward, and look like +this: +.PP +.Vb 2 +\& use threads; +\& use Thread::Queue; +\& +\& my $DataQueue = Thread::Queue\->new(); +\& my $thr = threads\->create(sub { +\& while (my $DataElement = $DataQueue\->dequeue()) { +\& print("Popped $DataElement off the queue\en"); +\& } +\& }); +\& +\& $DataQueue\->enqueue(12); +\& $DataQueue\->enqueue("A", "B", "C"); +\& sleep(10); +\& $DataQueue\->enqueue(undef); +\& $thr\->join(); +.Ve +.PP +You create the queue with \f(CW\*(C`Thread::Queue\->new()\*(C'\fR. Then you can +add lists of scalars onto the end with \f(CWenqueue()\fR, and pop scalars off +the front of it with \f(CWdequeue()\fR. A queue has no fixed size, and can grow +as needed to hold everything pushed on to it. +.PP +If a queue is empty, \f(CWdequeue()\fR blocks until another thread enqueues +something. This makes queues ideal for event loops and other +communications between threads. +.SS "Semaphores: Synchronizing Data Access" +.IX Subsection "Semaphores: Synchronizing Data Access" +Semaphores are a kind of generic locking mechanism. In their most basic +form, they behave very much like lockable scalars, except that they +can't hold data, and that they must be explicitly unlocked. In their +advanced form, they act like a kind of counter, and can allow multiple +threads to have the \fIlock\fR at any one time. +.SS "Basic semaphores" +.IX Subsection "Basic semaphores" +Semaphores have two methods, \f(CWdown()\fR and \f(CWup()\fR: \f(CWdown()\fR decrements the resource +count, while \f(CWup()\fR increments it. Calls to \f(CWdown()\fR will block if the +semaphore's current count would decrement below zero. This program +gives a quick demonstration: +.PP +.Vb 2 +\& use threads; +\& use Thread::Semaphore; +\& +\& my $semaphore = Thread::Semaphore\->new(); +\& my $GlobalVariable :shared = 0; +\& +\& $thr1 = threads\->create(\e&sample_sub, 1); +\& $thr2 = threads\->create(\e&sample_sub, 2); +\& $thr3 = threads\->create(\e&sample_sub, 3); +\& +\& sub sample_sub { +\& my $SubNumber = shift(@_); +\& my $TryCount = 10; +\& my $LocalCopy; +\& sleep(1); +\& while ($TryCount\-\-) { +\& $semaphore\->down(); +\& $LocalCopy = $GlobalVariable; +\& print("$TryCount tries left for sub $SubNumber " +\& ."(\e$GlobalVariable is $GlobalVariable)\en"); +\& sleep(2); +\& $LocalCopy++; +\& $GlobalVariable = $LocalCopy; +\& $semaphore\->up(); +\& } +\& } +\& +\& $thr1\->join(); +\& $thr2\->join(); +\& $thr3\->join(); +.Ve +.PP +The three invocations of the subroutine all operate in sync. The +semaphore, though, makes sure that only one thread is accessing the +global variable at once. +.SS "Advanced Semaphores" +.IX Subsection "Advanced Semaphores" +By default, semaphores behave like locks, letting only one thread +\&\f(CWdown()\fR them at a time. However, there are other uses for semaphores. +.PP +Each semaphore has a counter attached to it. By default, semaphores are +created with the counter set to one, \f(CWdown()\fR decrements the counter by +one, and \f(CWup()\fR increments by one. However, we can override any or all +of these defaults simply by passing in different values: +.PP +.Vb 2 +\& use threads; +\& use Thread::Semaphore; +\& +\& my $semaphore = Thread::Semaphore\->new(5); +\& # Creates a semaphore with the counter set to five +\& +\& my $thr1 = threads\->create(\e&sub1); +\& my $thr2 = threads\->create(\e&sub1); +\& +\& sub sub1 { +\& $semaphore\->down(5); # Decrements the counter by five +\& # Do stuff here +\& $semaphore\->up(5); # Increment the counter by five +\& } +\& +\& $thr1\->detach(); +\& $thr2\->detach(); +.Ve +.PP +If \f(CWdown()\fR attempts to decrement the counter below zero, it blocks until +the counter is large enough. Note that while a semaphore can be created +with a starting count of zero, any \f(CWup()\fR or \f(CWdown()\fR always changes the +counter by at least one, and so \f(CW\*(C`$semaphore\->down(0)\*(C'\fR is the same as +\&\f(CW\*(C`$semaphore\->down(1)\*(C'\fR. +.PP +The question, of course, is why would you do something like this? Why +create a semaphore with a starting count that's not one, or why +decrement or increment it by more than one? The answer is resource +availability. Many resources that you want to manage access for can be +safely used by more than one thread at once. +.PP +For example, let's take a GUI driven program. It has a semaphore that +it uses to synchronize access to the display, so only one thread is +ever drawing at once. Handy, but of course you don't want any thread +to start drawing until things are properly set up. In this case, you +can create a semaphore with a counter set to zero, and up it when +things are ready for drawing. +.PP +Semaphores with counters greater than one are also useful for +establishing quotas. Say, for example, that you have a number of +threads that can do I/O at once. You don't want all the threads +reading or writing at once though, since that can potentially swamp +your I/O channels, or deplete your process's quota of filehandles. You +can use a semaphore initialized to the number of concurrent I/O +requests (or open files) that you want at any one time, and have your +threads quietly block and unblock themselves. +.PP +Larger increments or decrements are handy in those cases where a +thread needs to check out or return a number of resources at once. +.SS "Waiting for a Condition" +.IX Subsection "Waiting for a Condition" +The functions \f(CWcond_wait()\fR and \f(CWcond_signal()\fR +can be used in conjunction with locks to notify +co-operating threads that a resource has become available. They are +very similar in use to the functions found in \f(CW\*(C`pthreads\*(C'\fR. However +for most purposes, queues are simpler to use and more intuitive. See +threads::shared for more details. +.SS "Giving up control" +.IX Subsection "Giving up control" +There are times when you may find it useful to have a thread +explicitly give up the CPU to another thread. You may be doing something +processor-intensive and want to make sure that the user-interface thread +gets called frequently. Regardless, there are times that you might want +a thread to give up the processor. +.PP +Perl's threading package provides the \f(CWyield()\fR function that does +this. \f(CWyield()\fR is pretty straightforward, and works like this: +.PP +.Vb 1 +\& use threads; +\& +\& sub loop { +\& my $thread = shift; +\& my $foo = 50; +\& while($foo\-\-) { print("In thread $thread\en"); } +\& threads\->yield(); +\& $foo = 50; +\& while($foo\-\-) { print("In thread $thread\en"); } +\& } +\& +\& my $thr1 = threads\->create(\e&loop, \*(Aqfirst\*(Aq); +\& my $thr2 = threads\->create(\e&loop, \*(Aqsecond\*(Aq); +\& my $thr3 = threads\->create(\e&loop, \*(Aqthird\*(Aq); +.Ve +.PP +It is important to remember that \f(CWyield()\fR is only a hint to give up the CPU, +it depends on your hardware, OS and threading libraries what actually happens. +\&\fBOn many operating systems, yield() is a no-op.\fR Therefore it is important +to note that one should not build the scheduling of the threads around +\&\f(CWyield()\fR calls. It might work on your platform but it won't work on another +platform. +.SH "General Thread Utility Routines" +.IX Header "General Thread Utility Routines" +We've covered the workhorse parts of Perl's threading package, and +with these tools you should be well on your way to writing threaded +code and packages. There are a few useful little pieces that didn't +really fit in anyplace else. +.SS "What Thread Am I In?" +.IX Subsection "What Thread Am I In?" +The \f(CW\*(C`threads\->self()\*(C'\fR class method provides your program with a way to +get an object representing the thread it's currently in. You can use this +object in the same way as the ones returned from thread creation. +.SS "Thread IDs" +.IX Subsection "Thread IDs" +\&\f(CWtid()\fR is a thread object method that returns the thread ID of the +thread the object represents. Thread IDs are integers, with the main +thread in a program being 0. Currently Perl assigns a unique TID to +every thread ever created in your program, assigning the first thread +to be created a TID of 1, and increasing the TID by 1 for each new +thread that's created. When used as a class method, \f(CW\*(C`threads\->tid()\*(C'\fR +can be used by a thread to get its own TID. +.SS "Are These Threads The Same?" +.IX Subsection "Are These Threads The Same?" +The \f(CWequal()\fR method takes two thread objects and returns true +if the objects represent the same thread, and false if they don't. +.PP +Thread objects also have an overloaded \f(CW\*(C`==\*(C'\fR comparison so that you can do +comparison on them as you would with normal objects. +.SS "What Threads Are Running?" +.IX Subsection "What Threads Are Running?" +\&\f(CW\*(C`threads\->list()\*(C'\fR returns a list of thread objects, one for each thread +that's currently running and not detached. Handy for a number of things, +including cleaning up at the end of your program (from the main Perl thread, +of course): +.PP +.Vb 4 +\& # Loop through all the threads +\& foreach my $thr (threads\->list()) { +\& $thr\->join(); +\& } +.Ve +.PP +If some threads have not finished running when the main Perl thread +ends, Perl will warn you about it and die, since it is impossible for Perl +to clean up itself while other threads are running. +.PP +NOTE: The main Perl thread (thread 0) is in a \fIdetached\fR state, and so +does not appear in the list returned by \f(CW\*(C`threads\->list()\*(C'\fR. +.SH "A Complete Example" +.IX Header "A Complete Example" +Confused yet? It's time for an example program to show some of the +things we've covered. This program finds prime numbers using threads. +.PP +.Vb 10 +\& 1 #!/usr/bin/perl +\& 2 # prime\-pthread, courtesy of Tom Christiansen +\& 3 +\& 4 use v5.36; +\& 5 +\& 6 use threads; +\& 7 use Thread::Queue; +\& 8 +\& 9 sub check_num ($upstream, $cur_prime) { +\& 10 my $kid; +\& 11 my $downstream = Thread::Queue\->new(); +\& 12 while (my $num = $upstream\->dequeue()) { +\& 13 next unless ($num % $cur_prime); +\& 14 if ($kid) { +\& 15 $downstream\->enqueue($num); +\& 16 } else { +\& 17 print("Found prime: $num\en"); +\& 18 $kid = threads\->create(\e&check_num, $downstream, $num); +\& 19 if (! $kid) { +\& 20 warn("Sorry. Ran out of threads.\en"); +\& 21 last; +\& 22 } +\& 23 } +\& 24 } +\& 25 if ($kid) { +\& 26 $downstream\->enqueue(undef); +\& 27 $kid\->join(); +\& 28 } +\& 29 } +\& 30 +\& 31 my $stream = Thread::Queue\->new(3..1000, undef); +\& 32 check_num($stream, 2); +.Ve +.PP +This program uses the pipeline model to generate prime numbers. Each +thread in the pipeline has an input queue that feeds numbers to be +checked, a prime number that it's responsible for, and an output queue +into which it funnels numbers that have failed the check. If the thread +has a number that's failed its check and there's no child thread, then +the thread must have found a new prime number. In that case, a new +child thread is created for that prime and stuck on the end of the +pipeline. +.PP +This probably sounds a bit more confusing than it really is, so let's +go through this program piece by piece and see what it does. (For +those of you who might be trying to remember exactly what a prime +number is, it's a number that's only evenly divisible by itself and 1.) +.PP +The bulk of the work is done by the \f(CWcheck_num()\fR subroutine, which +takes a reference to its input queue and a prime number that it's +responsible for. We create a new queue (line 11) and reserve a scalar +for the thread that we're likely to create later (line 10). +.PP +The while loop from line 12 to line 24 grabs a scalar off the input +queue and checks against the prime this thread is responsible +for. Line 13 checks to see if there's a remainder when we divide the +number to be checked by our prime. If there is one, the number +must not be evenly divisible by our prime, so we need to either pass +it on to the next thread if we've created one (line 15) or create a +new thread if we haven't. +.PP +The new thread creation is line 18. We pass on to it a reference to +the queue we've created, and the prime number we've found. In lines 19 +through 22, we check to make sure that our new thread got created, and +if not, we stop checking any remaining numbers in the queue. +.PP +Finally, once the loop terminates (because we got a 0 or \f(CW\*(C`undef\*(C'\fR in the +queue, which serves as a note to terminate), we pass on the notice to our +child, and wait for it to exit if we've created a child (lines 25 and +28). +.PP +Meanwhile, back in the main thread, we first create a queue (line 31) and +queue up all the numbers from 3 to 1000 for checking, plus a termination +notice. Then all we have to do to get the ball rolling is pass the queue +and the first prime to the \f(CWcheck_num()\fR subroutine (line 32). +.PP +That's how it works. It's pretty simple; as with many Perl programs, +the explanation is much longer than the program. +.SH "Different implementations of threads" +.IX Header "Different implementations of threads" +Some background on thread implementations from the operating system +viewpoint. There are three basic categories of threads: user-mode threads, +kernel threads, and multiprocessor kernel threads. +.PP +User-mode threads are threads that live entirely within a program and +its libraries. In this model, the OS knows nothing about threads. As +far as it's concerned, your process is just a process. +.PP +This is the easiest way to implement threads, and the way most OSes +start. The big disadvantage is that, since the OS knows nothing about +threads, if one thread blocks they all do. Typical blocking activities +include most system calls, most I/O, and things like \f(CWsleep()\fR. +.PP +Kernel threads are the next step in thread evolution. The OS knows +about kernel threads, and makes allowances for them. The main +difference between a kernel thread and a user-mode thread is +blocking. With kernel threads, things that block a single thread don't +block other threads. This is not the case with user-mode threads, +where the kernel blocks at the process level and not the thread level. +.PP +This is a big step forward, and can give a threaded program quite a +performance boost over non-threaded programs. Threads that block +performing I/O, for example, won't block threads that are doing other +things. Each process still has only one thread running at once, +though, regardless of how many CPUs a system might have. +.PP +Since kernel threading can interrupt a thread at any time, they will +uncover some of the implicit locking assumptions you may make in your +program. For example, something as simple as \f(CW\*(C`$x = $x + 2\*(C'\fR can behave +unpredictably with kernel threads if \f(CW$x\fR is visible to other +threads, as another thread may have changed \f(CW$x\fR between the time it +was fetched on the right hand side and the time the new value is +stored. +.PP +Multiprocessor kernel threads are the final step in thread +support. With multiprocessor kernel threads on a machine with multiple +CPUs, the OS may schedule two or more threads to run simultaneously on +different CPUs. +.PP +This can give a serious performance boost to your threaded program, +since more than one thread will be executing at the same time. As a +tradeoff, though, any of those nagging synchronization issues that +might not have shown with basic kernel threads will appear with a +vengeance. +.PP +In addition to the different levels of OS involvement in threads, +different OSes (and different thread implementations for a particular +OS) allocate CPU cycles to threads in different ways. +.PP +Cooperative multitasking systems have running threads give up control +if one of two things happen. If a thread calls a yield function, it +gives up control. It also gives up control if the thread does +something that would cause it to block, such as perform I/O. In a +cooperative multitasking implementation, one thread can starve all the +others for CPU time if it so chooses. +.PP +Preemptive multitasking systems interrupt threads at regular intervals +while the system decides which thread should run next. In a preemptive +multitasking system, one thread usually won't monopolize the CPU. +.PP +On some systems, there can be cooperative and preemptive threads +running simultaneously. (Threads running with realtime priorities +often behave cooperatively, for example, while threads running at +normal priorities behave preemptively.) +.PP +Most modern operating systems support preemptive multitasking nowadays. +.SH "Performance considerations" +.IX Header "Performance considerations" +The main thing to bear in mind when comparing Perl's \fIithreads\fR to other threading +models is the fact that for each new thread created, a complete copy of +all the variables and data of the parent thread has to be taken. Thus, +thread creation can be quite expensive, both in terms of memory usage and +time spent in creation. The ideal way to reduce these costs is to have a +relatively short number of long-lived threads, all created fairly early +on (before the base thread has accumulated too much data). Of course, this +may not always be possible, so compromises have to be made. However, after +a thread has been created, its performance and extra memory usage should +be little different than ordinary code. +.PP +Also note that under the current implementation, shared variables +use a little more memory and are a little slower than ordinary variables. +.SH "Process-scope Changes" +.IX Header "Process-scope Changes" +Note that while threads themselves are separate execution threads and +Perl data is thread-private unless explicitly shared, the threads can +affect process-scope state, affecting all the threads. +.PP +The most common example of this is changing the current working +directory using \f(CWchdir()\fR. One thread calls \f(CWchdir()\fR, and the working +directory of all the threads changes. +.PP +Even more drastic example of a process-scope change is \f(CWchroot()\fR: +the root directory of all the threads changes, and no thread can +undo it (as opposed to \f(CWchdir()\fR). +.PP +Further examples of process-scope changes include \f(CWumask()\fR and +changing uids and gids. +.PP +Thinking of mixing \f(CWfork()\fR and threads? Please lie down and wait +until the feeling passes. Be aware that the semantics of \f(CWfork()\fR vary +between platforms. For example, some Unix systems copy all the current +threads into the child process, while others only copy the thread that +called \f(CWfork()\fR. You have been warned! +.PP +Similarly, mixing signals and threads may be problematic. +Implementations are platform-dependent, and even the POSIX +semantics may not be what you expect (and Perl doesn't even +give you the full POSIX API). For example, there is no way to +guarantee that a signal sent to a multi-threaded Perl application +will get intercepted by any particular thread. (However, a recently +added feature does provide the capability to send signals between +threads. See "THREAD SIGNALLING" in threads for more details.) +.SH "Thread-Safety of System Libraries" +.IX Header "Thread-Safety of System Libraries" +Whether various library calls are thread-safe is outside the control +of Perl. Calls often suffering from not being thread-safe include: +\&\f(CWlocaltime()\fR, \f(CWgmtime()\fR, functions fetching user, group and +network information (such as \f(CWgetgrent()\fR, \f(CWgethostent()\fR, +\&\f(CWgetnetent()\fR and so on), \f(CWreaddir()\fR, \f(CWrand()\fR, and \f(CWsrand()\fR. In +general, calls that depend on some global external state. +.PP +If the system Perl is compiled in has thread-safe variants of such +calls, they will be used. Beyond that, Perl is at the mercy of +the thread-safety or \-unsafety of the calls. Please consult your +C library call documentation. +.PP +On some platforms the thread-safe library interfaces may fail if the +result buffer is too small (for example the user group databases may +be rather large, and the reentrant interfaces may have to carry around +a full snapshot of those databases). Perl will start with a small +buffer, but keep retrying and growing the result buffer +until the result fits. If this limitless growing sounds bad for +security or memory consumption reasons you can recompile Perl with +\&\f(CW\*(C`PERL_REENTRANT_MAXSIZE\*(C'\fR defined to the maximum number of bytes you will +allow. +.SH Conclusion +.IX Header "Conclusion" +A complete thread tutorial could fill a book (and has, many times), +but with what we've covered in this introduction, you should be well +on your way to becoming a threaded Perl expert. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +Annotated POD for threads: +<https://web.archive.org/web/20171028020148/http://annocpan.org/?mode=search&field=Module&name=threads> +.PP +Latest version of threads on CPAN: +<https://metacpan.org/pod/threads> +.PP +Annotated POD for threads::shared: +<https://web.archive.org/web/20171028020148/http://annocpan.org/?mode=search&field=Module&name=threads%3A%3Ashared> +.PP +Latest version of threads::shared on CPAN: +<https://metacpan.org/pod/threads::shared> +.PP +Perl threads mailing list: +<https://lists.perl.org/list/ithreads.html> +.SH Bibliography +.IX Header "Bibliography" +Here's a short bibliography courtesy of Jürgen Christoffel: +.SS "Introductory Texts" +.IX Subsection "Introductory Texts" +Birrell, Andrew D. An Introduction to Programming with +Threads. Digital Equipment Corporation, 1989, DEC-SRC Research Report +#35 online as +<https://www.hpl.hp.com/techreports/Compaq\-DEC/SRC\-RR\-35.pdf> +(highly recommended) +.PP +Robbins, Kay. A., and Steven Robbins. Practical Unix Programming: A +Guide to Concurrency, Communication, and +Multithreading. Prentice-Hall, 1996. +.PP +Lewis, Bill, and Daniel J. Berg. Multithreaded Programming with +Pthreads. Prentice Hall, 1997, ISBN 0\-13\-443698\-9 (a well-written +introduction to threads). +.PP +Nelson, Greg (editor). Systems Programming with Modula\-3. Prentice +Hall, 1991, ISBN 0\-13\-590464\-1. +.PP +Nichols, Bradford, Dick Buttlar, and Jacqueline Proulx Farrell. +Pthreads Programming. O'Reilly & Associates, 1996, ISBN 156592\-115\-1 +(covers POSIX threads). +.SS "OS-Related References" +.IX Subsection "OS-Related References" +Boykin, Joseph, David Kirschen, Alan Langerman, and Susan +LoVerso. Programming under Mach. Addison-Wesley, 1994, ISBN +0\-201\-52739\-1. +.PP +Tanenbaum, Andrew S. Distributed Operating Systems. Prentice Hall, +1995, ISBN 0\-13\-219908\-4 (great textbook). +.PP +Silberschatz, Abraham, and Peter B. Galvin. Operating System Concepts, +4th ed. Addison-Wesley, 1995, ISBN 0\-201\-59292\-4 +.SS "Other References" +.IX Subsection "Other References" +Arnold, Ken and James Gosling. The Java Programming Language, 2nd +ed. Addison-Wesley, 1998, ISBN 0\-201\-31006\-6. +.PP +comp.programming.threads FAQ, +<http://www.serpentine.com/~bos/threads\-faq/> +.PP +Le Sergent, T. and B. Berthomieu. "Incremental MultiThreaded Garbage +Collection on Virtually Shared Memory Architectures" in Memory +Management: Proc. of the International Workshop IWMM 92, St. Malo, +France, September 1992, Yves Bekkers and Jacques Cohen, eds. Springer, +1992, ISBN 3540\-55940\-X (real-life thread applications). +.PP +Artur Bergman, "Where Wizards Fear To Tread", June 11, 2002, +<http://www.perl.com/pub/a/2002/06/11/threads.html> +.SH Acknowledgements +.IX Header "Acknowledgements" +Thanks (in no particular order) to Chaim Frenkel, Steve Fink, Gurusamy +Sarathy, Ilya Zakharevich, Benjamin Sugars, Jürgen Christoffel, Joshua +Pritikin, and Alan Burlison, for their help in reality-checking and +polishing this article. Big thanks to Tom Christiansen for his rewrite +of the prime number generator. +.SH AUTHOR +.IX Header "AUTHOR" +Dan Sugalski <dan@sidhe.org> +.PP +Slightly modified by Arthur Bergman to fit the new thread model/module. +.PP +Reworked slightly by Jörg Walter <jwalt@cpan.org> to be more concise +about thread-safety of Perl code. +.PP +Rearranged slightly by Elizabeth Mattijsen <liz@dijkmat.nl> to put +less emphasis on \fByield()\fR. +.SH Copyrights +.IX Header "Copyrights" +The original version of this article originally appeared in The Perl +Journal #10, and is copyright 1998 The Perl Journal. It appears courtesy +of Jon Orwant and The Perl Journal. This document may be distributed +under the same terms as Perl itself. |