ext/threads/threads.pm

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