[Summary view] [Print] [Text view]

   1  package threads;
   2  
   3  use 5.008;
   4  
   5  use strict;
   6  use warnings;
   7  
   8  our $VERSION = '1.67';
   9  my $XS_VERSION = $VERSION;
  10  $VERSION = eval $VERSION;
  11  
  12  # Verify this Perl supports threads
  13  require Config;
  14  if (! $Config::Config{useithreads}) {
  15      die("This Perl not built to support threads\n");
  16  }
  17  
  18  # Complain if 'threads' is loaded after 'threads::shared'
  19  if ($threads::shared::threads_shared) {
  20      warn <<'_MSG_';
  21  Warning, threads::shared has already been loaded.  To
  22  enable shared variables, 'use threads' must be called
  23  before threads::shared or any module that uses it.
  24  _MSG_
  25  }
  26  
  27  # Declare that we have been loaded
  28  $threads::threads = 1;
  29  
  30  # Load the XS code
  31  require XSLoader;
  32  XSLoader::load('threads', $XS_VERSION);
  33  
  34  
  35  ### Export ###
  36  
  37  sub import
  38  {
  39      my $class = shift;   # Not used
  40  
  41      # Exported subroutines
  42      my @EXPORT = qw(async);
  43  
  44      # Handle args
  45      while (my $sym = shift) {
  46          if ($sym =~ /^(?:stack|exit)/i) {
  47              if (defined(my $arg = shift)) {
  48                  if ($sym =~ /^stack/i) {
  49                      threads->set_stack_size($arg);
  50                  } else {
  51                      $threads::thread_exit_only = $arg =~ /^thread/i;
  52                  }
  53              } else {
  54                  require Carp;
  55                  Carp::croak("threads: Missing argument for option: $sym");
  56              }
  57  
  58          } elsif ($sym =~ /^str/i) {
  59              import overload ('""' => \&tid);
  60  
  61          } elsif ($sym =~ /^(?::all|yield)$/) {
  62              push(@EXPORT, qw(yield));
  63  
  64          } else {
  65              require Carp;
  66              Carp::croak("threads: Unknown import option: $sym");
  67          }
  68      }
  69  
  70      # Export subroutine names
  71      my $caller = caller();
  72      foreach my $sym (@EXPORT) {
  73          no strict 'refs';
  74          *{$caller.'::'.$sym} = \&{$sym};
  75      }
  76  
  77      # Set stack size via environment variable
  78      if (exists($ENV{'PERL5_ITHREADS_STACK_SIZE'})) {
  79          threads->set_stack_size($ENV{'PERL5_ITHREADS_STACK_SIZE'});
  80      }
  81  }
  82  
  83  
  84  ### Methods, etc. ###
  85  
  86  # Exit from a thread (only)
  87  sub exit
  88  {
  89      my ($class, $status) = @_;
  90      if (! defined($status)) {
  91          $status = 0;
  92      }
  93  
  94      # Class method only
  95      if (ref($class)) {
  96          require Carp;
  97          Carp::croak('Usage: threads->exit(status)');
  98      }
  99  
 100      $class->set_thread_exit_only(1);
 101      CORE::exit($status);
 102  }
 103  
 104  # 'Constant' args for threads->list()
 105  sub threads::all      { }
 106  sub threads::running  { 1 }
 107  sub threads::joinable { 0 }
 108  
 109  # 'new' is an alias for 'create'
 110  *new = \&create;
 111  
 112  # 'async' is a function alias for the 'threads->create()' method
 113  sub async (&;@)
 114  {
 115      unshift(@_, 'threads');
 116      # Use "goto" trick to avoid pad problems from 5.8.1 (fixed in 5.8.2)
 117      goto &create;
 118  }
 119  
 120  # Thread object equality checking
 121  use overload (
 122      '==' => \&equal,
 123      '!=' => sub { ! equal(@_) },
 124      'fallback' => 1
 125  );
 126  
 127  1;
 128  
 129  __END__
 130  
 131  =head1 NAME
 132  
 133  threads - Perl interpreter-based threads
 134  
 135  =head1 VERSION
 136  
 137  This document describes threads version 1.67
 138  
 139  =head1 SYNOPSIS
 140  
 141      use threads ('yield',
 142                   'stack_size' => 64*4096,
 143                   'exit' => 'threads_only',
 144                   'stringify');
 145  
 146      sub start_thread {
 147          my @args = @_;
 148          print('Thread started: ', join(' ', @args), "\n");
 149      }
 150      my $thr = threads->create('start_thread', 'argument');
 151      $thr->join();
 152  
 153      threads->create(sub { print("I am a thread\n"); })->join();
 154  
 155      my $thr2 = async { foreach (@files) { ... } };
 156      $thr2->join();
 157      if (my $err = $thr2->error()) {
 158          warn("Thread error: $err\n");
 159      }
 160  
 161      # Invoke thread in list context (implicit) so it can return a list
 162      my ($thr) = threads->create(sub { return (qw/a b c/); });
 163      # or specify list context explicitly
 164      my $thr = threads->create({'context' => 'list'},
 165                                sub { return (qw/a b c/); });
 166      my @results = $thr->join();
 167  
 168      $thr->detach();
 169  
 170      # Get a thread's object
 171      $thr = threads->self();
 172      $thr = threads->object($tid);
 173  
 174      # Get a thread's ID
 175      $tid = threads->tid();
 176      $tid = $thr->tid();
 177      $tid = "$thr";
 178  
 179      # Give other threads a chance to run
 180      threads->yield();
 181      yield();
 182  
 183      # Lists of non-detached threads
 184      my @threads = threads->list();
 185      my $thread_count = threads->list();
 186  
 187      my @running = threads->list(threads::running);
 188      my @joinable = threads->list(threads::joinable);
 189  
 190      # Test thread objects
 191      if ($thr1 == $thr2) {
 192          ...
 193      }
 194  
 195      # Manage thread stack size
 196      $stack_size = threads->get_stack_size();
 197      $old_size = threads->set_stack_size(32*4096);
 198  
 199      # Create a thread with a specific context and stack size
 200      my $thr = threads->create({ 'context'    => 'list',
 201                                  'stack_size' => 32*4096,
 202                                  'exit'       => 'thread_only' },
 203                                \&foo);
 204  
 205      # Get thread's context
 206      my $wantarray = $thr->wantarray();
 207  
 208      # Check thread's state
 209      if ($thr->is_running()) {
 210          sleep(1);
 211      }
 212      if ($thr->is_joinable()) {
 213          $thr->join();
 214      }
 215  
 216      # Send a signal to a thread
 217      $thr->kill('SIGUSR1');
 218  
 219      # Exit a thread
 220      threads->exit();
 221  
 222  =head1 DESCRIPTION
 223  
 224  Perl 5.6 introduced something called interpreter threads.  Interpreter threads
 225  are different from I<5005threads> (the thread model of Perl 5.005) by creating
 226  a new Perl interpreter per thread, and not sharing any data or state between
 227  threads by default.
 228  
 229  Prior to Perl 5.8, this has only been available to people embedding Perl, and
 230  for emulating fork() on Windows.
 231  
 232  The I<threads> API is loosely based on the old Thread.pm API. It is very
 233  important to note that variables are not shared between threads, all variables
 234  are by default thread local.  To use shared variables one must also use
 235  L<threads::shared>:
 236  
 237      use threads;
 238      use threads::shared;
 239  
 240  It is also important to note that you must enable threads by doing C<use
 241  threads> as early as possible in the script itself, and that it is not
 242  possible to enable threading inside an C<eval "">, C<do>, C<require>, or
 243  C<use>.  In particular, if you are intending to share variables with
 244  L<threads::shared>, you must C<use threads> before you C<use threads::shared>.
 245  (C<threads> will emit a warning if you do it the other way around.)
 246  
 247  =over
 248  
 249  =item $thr = threads->create(FUNCTION, ARGS)
 250  
 251  This will create a new thread that will begin execution with the specified
 252  entry point function, and give it the I<ARGS> list as parameters.  It will
 253  return the corresponding threads object, or C<undef> if thread creation failed.
 254  
 255  I<FUNCTION> may either be the name of a function, an anonymous subroutine, or
 256  a code ref.
 257  
 258      my $thr = threads->create('func_name', ...);
 259          # or
 260      my $thr = threads->create(sub { ... }, ...);
 261          # or
 262      my $thr = threads->create(\&func, ...);
 263  
 264  The C<-E<gt>new()> method is an alias for C<-E<gt>create()>.
 265  
 266  =item $thr->join()
 267  
 268  This will wait for the corresponding thread to complete its execution.  When
 269  the thread finishes, C<-E<gt>join()> will return the return value(s) of the
 270  entry point function.
 271  
 272  The context (void, scalar or list) for the return value(s) for C<-E<gt>join()>
 273  is determined at the time of thread creation.
 274  
 275      # Create thread in list context (implicit)
 276      my ($thr1) = threads->create(sub {
 277                                      my @results = qw(a b c);
 278                                      return (@results);
 279                                   });
 280      #   or (explicit)
 281      my $thr1 = threads->create({'context' => 'list'},
 282                                 sub {
 283                                      my @results = qw(a b c);
 284                                      return (@results);
 285                                 });
 286      # Retrieve list results from thread
 287      my @res1 = $thr1->join();
 288  
 289      # Create thread in scalar context (implicit)
 290      my $thr2 = threads->create(sub {
 291                                      my $result = 42;
 292                                      return ($result);
 293                                   });
 294      # Retrieve scalar result from thread
 295      my $res2 = $thr2->join();
 296  
 297      # Create a thread in void context (explicit)
 298      my $thr3 = threads->create({'void' => 1},
 299                                 sub { print("Hello, world\n"); });
 300      # Join the thread in void context (i.e., no return value)
 301      $thr3->join();
 302  
 303  See L</"THREAD CONTEXT"> for more details.
 304  
 305  If the program exits without all threads having either been joined or
 306  detached, then a warning will be issued.
 307  
 308  Calling C<-E<gt>join()> or C<-E<gt>detach()> on an already joined thread will
 309  cause an error to be thrown.
 310  
 311  =item $thr->detach()
 312  
 313  Makes the thread unjoinable, and causes any eventual return value to be
 314  discarded.  When the program exits, any detached threads that are still
 315  running are silently terminated.
 316  
 317  If the program exits without all threads having either been joined or
 318  detached, then a warning will be issued.
 319  
 320  Calling C<-E<gt>join()> or C<-E<gt>detach()> on an already detached thread
 321  will cause an error to be thrown.
 322  
 323  =item threads->detach()
 324  
 325  Class method that allows a thread to detach itself.
 326  
 327  =item threads->self()
 328  
 329  Class method that allows a thread to obtain its own I<threads> object.
 330  
 331  =item $thr->tid()
 332  
 333  Returns the ID of the thread.  Thread IDs are unique integers with the main
 334  thread in a program being 0, and incrementing by 1 for every thread created.
 335  
 336  =item threads->tid()
 337  
 338  Class method that allows a thread to obtain its own ID.
 339  
 340  =item "$thr"
 341  
 342  If you add the C<stringify> import option to your C<use threads> declaration,
 343  then using a threads object in a string or a string context (e.g., as a hash
 344  key) will cause its ID to be used as the value:
 345  
 346      use threads qw(stringify);
 347  
 348      my $thr = threads->create(...);
 349      print("Thread $thr started...\n");  # Prints out: Thread 1 started...
 350  
 351  =item threads->object($tid)
 352  
 353  This will return the I<threads> object for the I<active> thread associated
 354  with the specified thread ID.  Returns C<undef> if there is no thread
 355  associated with the TID, if the thread is joined or detached, if no TID is
 356  specified or if the specified TID is undef.
 357  
 358  =item threads->yield()
 359  
 360  This is a suggestion to the OS to let this thread yield CPU time to other
 361  threads.  What actually happens is highly dependent upon the underlying
 362  thread implementation.
 363  
 364  You may do C<use threads qw(yield)>, and then just use C<yield()> in your
 365  code.
 366  
 367  =item threads->list()
 368  
 369  =item threads->list(threads::all)
 370  
 371  =item threads->list(threads::running)
 372  
 373  =item threads->list(threads::joinable)
 374  
 375  With no arguments (or using C<threads::all>) and in a list context, returns a
 376  list of all non-joined, non-detached I<threads> objects.  In a scalar context,
 377  returns a count of the same.
 378  
 379  With a I<true> argument (using C<threads::running>), returns a list of all
 380  non-joined, non-detached I<threads> objects that are still running.
 381  
 382  With a I<false> argument (using C<threads::joinable>), returns a list of all
 383  non-joined, non-detached I<threads> objects that have finished running (i.e.,
 384  for which C<-E<gt>join()> will not I<block>).
 385  
 386  =item $thr1->equal($thr2)
 387  
 388  Tests if two threads objects are the same thread or not.  This is overloaded
 389  to the more natural forms:
 390  
 391      if ($thr1 == $thr2) {
 392          print("Threads are the same\n");
 393      }
 394      # or
 395      if ($thr1 != $thr2) {
 396          print("Threads differ\n");
 397      }
 398  
 399  (Thread comparison is based on thread IDs.)
 400  
 401  =item async BLOCK;
 402  
 403  C<async> creates a thread to execute the block immediately following
 404  it.  This block is treated as an anonymous subroutine, and so must have a
 405  semicolon after the closing brace.  Like C<threads-E<gt>create()>, C<async>
 406  returns a I<threads> object.
 407  
 408  =item $thr->error()
 409  
 410  Threads are executed in an C<eval> context.  This method will return C<undef>
 411  if the thread terminates I<normally>.  Otherwise, it returns the value of
 412  C<$@> associated with the thread's execution status in its C<eval> context.
 413  
 414  =item $thr->_handle()
 415  
 416  This I<private> method returns the memory location of the internal thread
 417  structure associated with a threads object.  For Win32, this is a pointer to
 418  the C<HANDLE> value returned by C<CreateThread> (i.e., C<HANDLE *>); for other
 419  platforms, it is a pointer to the C<pthread_t> structure used in the
 420  C<pthread_create> call (i.e., C<pthread_t *>).
 421  
 422  This method is of no use for general Perl threads programming.  Its intent is
 423  to provide other (XS-based) thread modules with the capability to access, and
 424  possibly manipulate, the underlying thread structure associated with a Perl
 425  thread.
 426  
 427  =item threads->_handle()
 428  
 429  Class method that allows a thread to obtain its own I<handle>.
 430  
 431  =back
 432  
 433  =head1 EXITING A THREAD
 434  
 435  The usual method for terminating a thread is to
 436  L<return()|perlfunc/"return EXPR"> from the entry point function with the
 437  appropriate return value(s).
 438  
 439  =over
 440  
 441  =item threads->exit()
 442  
 443  If needed, a thread can be exited at any time by calling
 444  C<threads-E<gt>exit()>.  This will cause the thread to return C<undef> in a
 445  scalar context, or the empty list in a list context.
 446  
 447  When called from the I<main> thread, this behaves the same as C<exit(0)>.
 448  
 449  =item threads->exit(status)
 450  
 451  When called from a thread, this behaves like C<threads-E<gt>exit()> (i.e., the
 452  exit status code is ignored).
 453  
 454  When called from the I<main> thread, this behaves the same as C<exit(status)>.
 455  
 456  =item die()
 457  
 458  Calling C<die()> in a thread indicates an abnormal exit for the thread.  Any
 459  C<$SIG{__DIE__}> handler in the thread will be called first, and then the
 460  thread will exit with a warning message that will contain any arguments passed
 461  in the C<die()> call.
 462  
 463  =item exit(status)
 464  
 465  Calling L<exit()|perlfunc/"exit EXPR"> inside a thread causes the whole
 466  application to terminate.  Because of this, the use of C<exit()> inside
 467  threaded code, or in modules that might be used in threaded applications, is
 468  strongly discouraged.
 469  
 470  If C<exit()> really is needed, then consider using the following:
 471  
 472      threads->exit() if threads->can('exit');   # Thread friendly
 473      exit(status);
 474  
 475  =item use threads 'exit' => 'threads_only'
 476  
 477  This globally overrides the default behavior of calling C<exit()> inside a
 478  thread, and effectively causes such calls to behave the same as
 479  C<threads-E<gt>exit()>.  In other words, with this setting, calling C<exit()>
 480  causes only the thread to terminate.
 481  
 482  Because of its global effect, this setting should not be used inside modules
 483  or the like.
 484  
 485  The I<main> thread is unaffected by this setting.
 486  
 487  =item threads->create({'exit' => 'thread_only'}, ...)
 488  
 489  This overrides the default behavior of C<exit()> inside the newly created
 490  thread only.
 491  
 492  =item $thr->set_thread_exit_only(boolean)
 493  
 494  This can be used to change the I<exit thread only> behavior for a thread after
 495  it has been created.  With a I<true> argument, C<exit()> will cause only the
 496  thread to exit.  With a I<false> argument, C<exit()> will terminate the
 497  application.
 498  
 499  The I<main> thread is unaffected by this call.
 500  
 501  =item threads->set_thread_exit_only(boolean)
 502  
 503  Class method for use inside a thread to change its own behavior for C<exit()>.
 504  
 505  The I<main> thread is unaffected by this call.
 506  
 507  =back
 508  
 509  =head1 THREAD STATE
 510  
 511  The following boolean methods are useful in determining the I<state> of a
 512  thread.
 513  
 514  =over
 515  
 516  =item $thr->is_running()
 517  
 518  Returns true if a thread is still running (i.e., if its entry point function
 519  has not yet finished or exited).
 520  
 521  =item $thr->is_joinable()
 522  
 523  Returns true if the thread has finished running, is not detached and has not
 524  yet been joined.  In other words, the thread is ready to be joined, and a call
 525  to C<$thr-E<gt>join()> will not I<block>.
 526  
 527  =item $thr->is_detached()
 528  
 529  Returns true if the thread has been detached.
 530  
 531  =item threads->is_detached()
 532  
 533  Class method that allows a thread to determine whether or not it is detached.
 534  
 535  =back
 536  
 537  =head1 THREAD CONTEXT
 538  
 539  As with subroutines, the type of value returned from a thread's entry point
 540  function may be determined by the thread's I<context>:  list, scalar or void.
 541  The thread's context is determined at thread creation.  This is necessary so
 542  that the context is available to the entry point function via
 543  L<wantarray()|perlfunc/"wantarray">.  The thread may then specify a value of
 544  the appropriate type to be returned from C<-E<gt>join()>.
 545  
 546  =head2 Explicit context
 547  
 548  Because thread creation and thread joining may occur in different contexts, it
 549  may be desirable to state the context explicitly to the thread's entry point
 550  function.  This may be done by calling C<-E<gt>create()> with a hash reference
 551  as the first argument:
 552  
 553      my $thr = threads->create({'context' => 'list'}, \&foo);
 554      ...
 555      my @results = $thr->join();
 556  
 557  In the above, the threads object is returned to the parent thread in scalar
 558  context, and the thread's entry point function C<foo> will be called in list
 559  (array) context such that the parent thread can receive a list (array) from
 560  the C<-E<gt>join()> call.  (C<'array'> is synonymous with C<'list'>.)
 561  
 562  Similarly, if you need the threads object, but your thread will not be
 563  returning a value (i.e., I<void> context), you would do the following:
 564  
 565      my $thr = threads->create({'context' => 'void'}, \&foo);
 566      ...
 567      $thr->join();
 568  
 569  The context type may also be used as the I<key> in the hash reference followed
 570  by a I<true> value:
 571  
 572      threads->create({'scalar' => 1}, \&foo);
 573      ...
 574      my ($thr) = threads->list();
 575      my $result = $thr->join();
 576  
 577  =head2 Implicit context
 578  
 579  If not explicitly stated, the thread's context is implied from the context
 580  of the C<-E<gt>create()> call:
 581  
 582      # Create thread in list context
 583      my ($thr) = threads->create(...);
 584  
 585      # Create thread in scalar context
 586      my $thr = threads->create(...);
 587  
 588      # Create thread in void context
 589      threads->create(...);
 590  
 591  =head2 $thr->wantarray()
 592  
 593  This returns the thread's context in the same manner as
 594  L<wantarray()|perlfunc/"wantarray">.
 595  
 596  =head2 threads->wantarray()
 597  
 598  Class method to return the current thread's context.  This returns the same
 599  value as running L<wantarray()|perlfunc/"wantarray"> inside the current
 600  thread's entry point function.
 601  
 602  =head1 THREAD STACK SIZE
 603  
 604  The default per-thread stack size for different platforms varies
 605  significantly, and is almost always far more than is needed for most
 606  applications.  On Win32, Perl's makefile explicitly sets the default stack to
 607  16 MB; on most other platforms, the system default is used, which again may be
 608  much larger than is needed.
 609  
 610  By tuning the stack size to more accurately reflect your application's needs,
 611  you may significantly reduce your application's memory usage, and increase the
 612  number of simultaneously running threads.
 613  
 614  Note that on Windows, address space allocation granularity is 64 KB,
 615  therefore, setting the stack smaller than that on Win32 Perl will not save any
 616  more memory.
 617  
 618  =over
 619  
 620  =item threads->get_stack_size();
 621  
 622  Returns the current default per-thread stack size.  The default is zero, which
 623  means the system default stack size is currently in use.
 624  
 625  =item $size = $thr->get_stack_size();
 626  
 627  Returns the stack size for a particular thread.  A return value of zero
 628  indicates the system default stack size was used for the thread.
 629  
 630  =item $old_size = threads->set_stack_size($new_size);
 631  
 632  Sets a new default per-thread stack size, and returns the previous setting.
 633  
 634  Some platforms have a minimum thread stack size.  Trying to set the stack size
 635  below this value will result in a warning, and the minimum stack size will be
 636  used.
 637  
 638  Some Linux platforms have a maximum stack size.  Setting too large of a stack
 639  size will cause thread creation to fail.
 640  
 641  If needed, C<$new_size> will be rounded up to the next multiple of the memory
 642  page size (usually 4096 or 8192).
 643  
 644  Threads created after the stack size is set will then either call
 645  C<pthread_attr_setstacksize()> I<(for pthreads platforms)>, or supply the
 646  stack size to C<CreateThread()> I<(for Win32 Perl)>.
 647  
 648  (Obviously, this call does not affect any currently extant threads.)
 649  
 650  =item use threads ('stack_size' => VALUE);
 651  
 652  This sets the default per-thread stack size at the start of the application.
 653  
 654  =item $ENV{'PERL5_ITHREADS_STACK_SIZE'}
 655  
 656  The default per-thread stack size may be set at the start of the application
 657  through the use of the environment variable C<PERL5_ITHREADS_STACK_SIZE>:
 658  
 659      PERL5_ITHREADS_STACK_SIZE=1048576
 660      export PERL5_ITHREADS_STACK_SIZE
 661      perl -e'use threads; print(threads->get_stack_size(), "\n")'
 662  
 663  This value overrides any C<stack_size> parameter given to C<use threads>.  Its
 664  primary purpose is to permit setting the per-thread stack size for legacy
 665  threaded applications.
 666  
 667  =item threads->create({'stack_size' => VALUE}, FUNCTION, ARGS)
 668  
 669  To specify a particular stack size for any individual thread, call
 670  C<-E<gt>create()> with a hash reference as the first argument:
 671  
 672      my $thr = threads->create({'stack_size' => 32*4096}, \&foo, @args);
 673  
 674  =item $thr2 = $thr1->create(FUNCTION, ARGS)
 675  
 676  This creates a new thread (C<$thr2>) that inherits the stack size from an
 677  existing thread (C<$thr1>).  This is shorthand for the following:
 678  
 679      my $stack_size = $thr1->get_stack_size();
 680      my $thr2 = threads->create({'stack_size' => $stack_size}, FUNCTION, ARGS);
 681  
 682  =back
 683  
 684  =head1 THREAD SIGNALLING
 685  
 686  When safe signals is in effect (the default behavior - see L</"Unsafe signals">
 687  for more details), then signals may be sent and acted upon by individual
 688  threads.
 689  
 690  =over 4
 691  
 692  =item $thr->kill('SIG...');
 693  
 694  Sends the specified signal to the thread.  Signal names and (positive) signal
 695  numbers are the same as those supported by
 696  L<kill()|perlfunc/"kill SIGNAL, LIST">.  For example, 'SIGTERM', 'TERM' and
 697  (depending on the OS) 15 are all valid arguments to C<-E<gt>kill()>.
 698  
 699  Returns the thread object to allow for method chaining:
 700  
 701      $thr->kill('SIG...')->join();
 702  
 703  =back
 704  
 705  Signal handlers need to be set up in the threads for the signals they are
 706  expected to act upon.  Here's an example for I<cancelling> a thread:
 707  
 708      use threads;
 709  
 710      sub thr_func
 711      {
 712          # Thread 'cancellation' signal handler
 713          $SIG{'KILL'} = sub { threads->exit(); };
 714  
 715          ...
 716      }
 717  
 718      # Create a thread
 719      my $thr = threads->create('thr_func');
 720  
 721      ...
 722  
 723      # Signal the thread to terminate, and then detach
 724      # it so that it will get cleaned up automatically
 725      $thr->kill('KILL')->detach();
 726  
 727  Here's another simplistic example that illustrates the use of thread
 728  signalling in conjunction with a semaphore to provide rudimentary I<suspend>
 729  and I<resume> capabilities:
 730  
 731      use threads;
 732      use Thread::Semaphore;
 733  
 734      sub thr_func
 735      {
 736          my $sema = shift;
 737  
 738          # Thread 'suspend/resume' signal handler
 739          $SIG{'STOP'} = sub {
 740              $sema->down();      # Thread suspended
 741              $sema->up();        # Thread resumes
 742          };
 743  
 744          ...
 745      }
 746  
 747      # Create a semaphore and pass it to a thread
 748      my $sema = Thread::Semaphore->new();
 749      my $thr = threads->create('thr_func', $sema);
 750  
 751      # Suspend the thread
 752      $sema->down();
 753      $thr->kill('STOP');
 754  
 755      ...
 756  
 757      # Allow the thread to continue
 758      $sema->up();
 759  
 760  CAVEAT:  The thread signalling capability provided by this module does not
 761  actually send signals via the OS.  It I<emulates> signals at the Perl-level
 762  such that signal handlers are called in the appropriate thread.  For example,
 763  sending C<$thr-E<gt>kill('STOP')> does not actually suspend a thread (or the
 764  whole process), but does cause a C<$SIG{'STOP'}> handler to be called in that
 765  thread (as illustrated above).
 766  
 767  As such, signals that would normally not be appropriate to use in the
 768  C<kill()> command (e.g., C<kill('KILL', $$)>) are okay to use with the
 769  C<-E<gt>kill()> method (again, as illustrated above).
 770  
 771  Correspondingly, sending a signal to a thread does not disrupt the operation
 772  the thread is currently working on:  The signal will be acted upon after the
 773  current operation has completed.  For instance, if the thread is I<stuck> on
 774  an I/O call, sending it a signal will not cause the I/O call to be interrupted
 775  such that the signal is acted up immediately.
 776  
 777  Sending a signal to a terminated thread is ignored.
 778  
 779  =head1 WARNINGS
 780  
 781  =over 4
 782  
 783  =item Perl exited with active threads:
 784  
 785  If the program exits without all threads having either been joined or
 786  detached, then this warning will be issued.
 787  
 788  NOTE:  If the I<main> thread exits, then this warning cannot be suppressed
 789  using C<no warnings 'threads';> as suggested below.
 790  
 791  =item Thread creation failed: pthread_create returned #
 792  
 793  See the appropriate I<man> page for C<pthread_create> to determine the actual
 794  cause for the failure.
 795  
 796  =item Thread # terminated abnormally: ...
 797  
 798  A thread terminated in some manner other than just returning from its entry
 799  point function, or by using C<threads-E<gt>exit()>.  For example, the thread
 800  may have terminated because of an error, or by using C<die>.
 801  
 802  =item Using minimum thread stack size of #
 803  
 804  Some platforms have a minimum thread stack size.  Trying to set the stack size
 805  below this value will result in the above warning, and the stack size will be
 806  set to the minimum.
 807  
 808  =item Thread creation failed: pthread_attr_setstacksize(I<SIZE>) returned 22
 809  
 810  The specified I<SIZE> exceeds the system's maximum stack size.  Use a smaller
 811  value for the stack size.
 812  
 813  =back
 814  
 815  If needed, thread warnings can be suppressed by using:
 816  
 817      no warnings 'threads';
 818  
 819  in the appropriate scope.
 820  
 821  =head1 ERRORS
 822  
 823  =over 4
 824  
 825  =item This Perl not built to support threads
 826  
 827  The particular copy of Perl that you're trying to use was not built using the
 828  C<useithreads> configuration option.
 829  
 830  Having threads support requires all of Perl and all of the XS modules in the
 831  Perl installation to be rebuilt; it is not just a question of adding the
 832  L<threads> module (i.e., threaded and non-threaded Perls are binary
 833  incompatible.)
 834  
 835  =item Cannot change stack size of an existing thread
 836  
 837  The stack size of currently extant threads cannot be changed, therefore, the
 838  following results in the above error:
 839  
 840      $thr->set_stack_size($size);
 841  
 842  =item Cannot signal threads without safe signals
 843  
 844  Safe signals must be in effect to use the C<-E<gt>kill()> signalling method.
 845  See L</"Unsafe signals"> for more details.
 846  
 847  =item Unrecognized signal name: ...
 848  
 849  The particular copy of Perl that you're trying to use does not support the
 850  specified signal being used in a C<-E<gt>kill()> call.
 851  
 852  =back
 853  
 854  =head1 BUGS AND LIMITATIONS
 855  
 856  Before you consider posting a bug report, please consult, and possibly post a
 857  message to the discussion forum to see if what you've encountered is a known
 858  problem.
 859  
 860  =over
 861  
 862  =item Thread-safe modules
 863  
 864  See L<perlmod/"Making your module threadsafe"> when creating modules that may
 865  be used in threaded applications, especially if those modules use non-Perl
 866  data, or XS code.
 867  
 868  =item Using non-thread-safe modules
 869  
 870  Unfortunately, you may encounter Perl modules that are not I<thread-safe>.
 871  For example, they may crash the Perl interpreter during execution, or may dump
 872  core on termination.  Depending on the module and the requirements of your
 873  application, it may be possible to work around such difficulties.
 874  
 875  If the module will only be used inside a thread, you can try loading the
 876  module from inside the thread entry point function using C<require> (and
 877  C<import> if needed):
 878  
 879      sub thr_func
 880      {
 881          require Unsafe::Module
 882          # Unsafe::Module->import(...);
 883  
 884          ....
 885      }
 886  
 887  If the module is needed inside the I<main> thread, try modifying your
 888  application so that the module is loaded (again using C<require> and
 889  C<-E<gt>import()>) after any threads are started, and in such a way that no
 890  other threads are started afterwards.
 891  
 892  If the above does not work, or is not adequate for your application, then file
 893  a bug report on L<http://rt.cpan.org/Public/> against the problematic module.
 894  
 895  =item Current working directory
 896  
 897  On all platforms except MSWin32, the setting for the current working directory
 898  is shared among all threads such that changing it in one thread (e.g., using
 899  C<chdir()>) will affect all the threads in the application.
 900  
 901  On MSWin32, each thread maintains its own the current working directory
 902  setting.
 903  
 904  =item Environment variables
 905  
 906  Currently, on all platforms except MSWin32, all I<system> calls (e.g., using
 907  C<system()> or back-ticks) made from threads use the environment variable
 908  settings from the I<main> thread.  In other words, changes made to C<%ENV> in
 909  a thread will not be visible in I<system> calls made by that thread.
 910  
 911  To work around this, set environment variables as part of the I<system> call.
 912  For example:
 913  
 914      my $msg = 'hello';
 915      system("FOO=$msg; echo \$FOO");   # Outputs 'hello' to STDOUT
 916  
 917  On MSWin32, each thread maintains its own set of environment variables.
 918  
 919  =item Parent-child threads
 920  
 921  On some platforms, it might not be possible to destroy I<parent> threads while
 922  there are still existing I<child> threads.
 923  
 924  =item Creating threads inside special blocks
 925  
 926  Creating threads inside C<BEGIN>, C<CHECK> or C<INIT> blocks should not be
 927  relied upon.  Depending on the Perl version and the application code, results
 928  may range from success, to (apparently harmless) warnings of leaked scalar, or
 929  all the way up to crashing of the Perl interpreter.
 930  
 931  =item Unsafe signals
 932  
 933  Since Perl 5.8.0, signals have been made safer in Perl by postponing their
 934  handling until the interpreter is in a I<safe> state.  See
 935  L<perl58delta/"Safe Signals"> and L<perlipc/"Deferred Signals (Safe Signals)">
 936  for more details.
 937  
 938  Safe signals is the default behavior, and the old, immediate, unsafe
 939  signalling behavior is only in effect in the following situations:
 940  
 941  =over 4
 942  
 943  =item * Perl has been built with C<PERL_OLD_SIGNALS> (see C<perl -V>).
 944  
 945  =item * The environment variable C<PERL_SIGNALS> is set to C<unsafe> (see L<perlrun/"PERL_SIGNALS">).
 946  
 947  =item * The module L<Perl::Unsafe::Signals> is used.
 948  
 949  =back
 950  
 951  If unsafe signals is in effect, then signal handling is not thread-safe, and
 952  the C<-E<gt>kill()> signalling method cannot be used.
 953  
 954  =item Returning closures from threads
 955  
 956  Returning closures from threads should not be relied upon.  Depending of the
 957  Perl version and the application code, results may range from success, to
 958  (apparently harmless) warnings of leaked scalar, or all the way up to crashing
 959  of the Perl interpreter.
 960  
 961  =item Returning objects from threads
 962  
 963  Returning objects from threads does not work.  Depending on the classes
 964  involved, you may be able to work around this by returning a serialized
 965  version of the object (e.g., using L<Data::Dumper> or L<Storable>), and then
 966  reconstituting it in the joining thread.
 967  
 968  =item Perl Bugs and the CPAN Version of L<threads>
 969  
 970  Support for threads extends beyond the code in this module (i.e.,
 971  F<threads.pm> and F<threads.xs>), and into the Perl interpreter itself.  Older
 972  versions of Perl contain bugs that may manifest themselves despite using the
 973  latest version of L<threads> from CPAN.  There is no workaround for this other
 974  than upgrading to the latest version of Perl.
 975  
 976  Even with the latest version of Perl, it is known that certain constructs
 977  with threads may result in warning messages concerning leaked scalars or
 978  unreferenced scalars.  However, such warnings are harmless, and may safely be
 979  ignored.
 980  
 981  =back
 982  
 983  =head1 REQUIREMENTS
 984  
 985  Perl 5.8.0 or later
 986  
 987  =head1 SEE ALSO
 988  
 989  L<threads> Discussion Forum on CPAN:
 990  L<http://www.cpanforum.com/dist/threads>
 991  
 992  Annotated POD for L<threads>:
 993  L<http://annocpan.org/~JDHEDDEN/threads-1.67/threads.pm>
 994  
 995  Source repository:
 996  L<http://code.google.com/p/threads-shared/>
 997  
 998  L<threads::shared>, L<perlthrtut>
 999  
1000  L<http://www.perl.com/pub/a/2002/06/11/threads.html> and
1001  L<http://www.perl.com/pub/a/2002/09/04/threads.html>
1002  
1003  Perl threads mailing list:
1004  L<http://lists.cpan.org/showlist.cgi?name=iThreads>
1005  
1006  Stack size discussion:
1007  L<http://www.perlmonks.org/?node_id=532956>
1008  
1009  =head1 AUTHOR
1010  
1011  Artur Bergman E<lt>sky AT crucially DOT netE<gt>
1012  
1013  threads is released under the same license as Perl.
1014  
1015  CPAN version produced by Jerry D. Hedden <jdhedden AT cpan DOT org>
1016  
1017  =head1 ACKNOWLEDGEMENTS
1018  
1019  Richard Soderberg E<lt>perl AT crystalflame DOT netE<gt> -
1020  Helping me out tons, trying to find reasons for races and other weird bugs!
1021  
1022  Simon Cozens E<lt>simon AT brecon DOT co DOT ukE<gt> -
1023  Being there to answer zillions of annoying questions
1024  
1025  Rocco Caputo E<lt>troc AT netrus DOT netE<gt>
1026  
1027  Vipul Ved Prakash E<lt>mail AT vipul DOT netE<gt> -
1028  Helping with debugging
1029  
1030  Dean Arnold E<lt>darnold AT presicient DOT comE<gt> -
1031  Stack size API
1032  
1033  =cut