[Summary view] [Print] [Text view]

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