ext/threads/threads.pm

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