This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
f2517bea08453f1f32aa484de121320761ed76c0
[perl5.git] / dist / threads / lib / threads.pm
1 package threads;
2
3 use 5.008;
4
5 use strict;
6 use warnings;
7
8 our $VERSION = '1.89';
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.89
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 Since Perl 5.8, thread programming has been available using a model called
225 I<interpreter threads> which provides a new Perl interpreter for each
226 thread, and, by default, results in no data or state information being shared
227 between threads.
228
229 (Prior to Perl 5.8, I<5005threads> was available through the C<Thread.pm> API.
230 This threading model has been deprecated, and was removed as of Perl 5.10.0.)
231
232 As just mentioned, all variables are, by default, thread local.  To use shared
233 variables, you need to also load L<threads::shared>:
234
235     use threads;
236     use threads::shared;
237
238 When loading L<threads::shared>, you must C<use threads> before you
239 C<use threads::shared>.  (C<threads> will emit a warning if you do it the
240 other way around.)
241
242 It is strongly recommended that you enable threads via C<use threads> as early
243 as possible in your script.
244
245 If needed, scripts can be written so as to run on both threaded and
246 non-threaded Perls:
247
248     my $can_use_threads = eval 'use threads; 1';
249     if ($can_use_threads) {
250         # Do processing using threads
251         ...
252     } else {
253         # Do it without using threads
254         ...
255     }
256
257 =over
258
259 =item $thr = threads->create(FUNCTION, ARGS)
260
261 This will create a new thread that will begin execution with the specified
262 entry point function, and give it the I<ARGS> list as parameters.  It will
263 return the corresponding threads object, or C<undef> if thread creation failed.
264
265 I<FUNCTION> may either be the name of a function, an anonymous subroutine, or
266 a code ref.
267
268     my $thr = threads->create('func_name', ...);
269         # or
270     my $thr = threads->create(sub { ... }, ...);
271         # or
272     my $thr = threads->create(\&func, ...);
273
274 The C<-E<gt>new()> method is an alias for C<-E<gt>create()>.
275
276 =item $thr->join()
277
278 This will wait for the corresponding thread to complete its execution.  When
279 the thread finishes, C<-E<gt>join()> will return the return value(s) of the
280 entry point function.
281
282 The context (void, scalar or list) for the return value(s) for C<-E<gt>join()>
283 is determined at the time of thread creation.
284
285     # Create thread in list context (implicit)
286     my ($thr1) = threads->create(sub {
287                                     my @results = qw(a b c);
288                                     return (@results);
289                                  });
290     #   or (explicit)
291     my $thr1 = threads->create({'context' => 'list'},
292                                sub {
293                                     my @results = qw(a b c);
294                                     return (@results);
295                                });
296     # Retrieve list results from thread
297     my @res1 = $thr1->join();
298
299     # Create thread in scalar context (implicit)
300     my $thr2 = threads->create(sub {
301                                     my $result = 42;
302                                     return ($result);
303                                  });
304     # Retrieve scalar result from thread
305     my $res2 = $thr2->join();
306
307     # Create a thread in void context (explicit)
308     my $thr3 = threads->create({'void' => 1},
309                                sub { print("Hello, world\n"); });
310     # Join the thread in void context (i.e., no return value)
311     $thr3->join();
312
313 See L</"THREAD CONTEXT"> for more details.
314
315 If the program exits without all threads having either been joined or
316 detached, then a warning will be issued.
317
318 Calling C<-E<gt>join()> or C<-E<gt>detach()> on an already joined thread will
319 cause an error to be thrown.
320
321 =item $thr->detach()
322
323 Makes the thread unjoinable, and causes any eventual return value to be
324 discarded.  When the program exits, any detached threads that are still
325 running are silently terminated.
326
327 If the program exits without all threads having either been joined or
328 detached, then a warning will be issued.
329
330 Calling C<-E<gt>join()> or C<-E<gt>detach()> on an already detached thread
331 will cause an error to be thrown.
332
333 =item threads->detach()
334
335 Class method that allows a thread to detach itself.
336
337 =item threads->self()
338
339 Class method that allows a thread to obtain its own I<threads> object.
340
341 =item $thr->tid()
342
343 Returns the ID of the thread.  Thread IDs are unique integers with the main
344 thread in a program being 0, and incrementing by 1 for every thread created.
345
346 =item threads->tid()
347
348 Class method that allows a thread to obtain its own ID.
349
350 =item "$thr"
351
352 If you add the C<stringify> import option to your C<use threads> declaration,
353 then using a threads object in a string or a string context (e.g., as a hash
354 key) will cause its ID to be used as the value:
355
356     use threads qw(stringify);
357
358     my $thr = threads->create(...);
359     print("Thread $thr started...\n");  # Prints out: Thread 1 started...
360
361 =item threads->object($tid)
362
363 This will return the I<threads> object for the I<active> thread associated
364 with the specified thread ID.  If C<$tid> is the value for the current thread,
365 then this call works the same as C<-E<gt>self()>.  Otherwise, returns C<undef>
366 if there is no thread associated with the TID, if the thread is joined or
367 detached, if no TID is specified or if the specified TID is undef.
368
369 =item threads->yield()
370
371 This is a suggestion to the OS to let this thread yield CPU time to other
372 threads.  What actually happens is highly dependent upon the underlying
373 thread implementation.
374
375 You may do C<use threads qw(yield)>, and then just use C<yield()> in your
376 code.
377
378 =item threads->list()
379
380 =item threads->list(threads::all)
381
382 =item threads->list(threads::running)
383
384 =item threads->list(threads::joinable)
385
386 With no arguments (or using C<threads::all>) and in a list context, returns a
387 list of all non-joined, non-detached I<threads> objects.  In a scalar context,
388 returns a count of the same.
389
390 With a I<true> argument (using C<threads::running>), returns a list of all
391 non-joined, non-detached I<threads> objects that are still running.
392
393 With a I<false> argument (using C<threads::joinable>), returns a list of all
394 non-joined, non-detached I<threads> objects that have finished running (i.e.,
395 for which C<-E<gt>join()> will not I<block>).
396
397 =item $thr1->equal($thr2)
398
399 Tests if two threads objects are the same thread or not.  This is overloaded
400 to the more natural forms:
401
402     if ($thr1 == $thr2) {
403         print("Threads are the same\n");
404     }
405     # or
406     if ($thr1 != $thr2) {
407         print("Threads differ\n");
408     }
409
410 (Thread comparison is based on thread IDs.)
411
412 =item async BLOCK;
413
414 C<async> creates a thread to execute the block immediately following
415 it.  This block is treated as an anonymous subroutine, and so must have a
416 semicolon after the closing brace.  Like C<threads-E<gt>create()>, C<async>
417 returns a I<threads> object.
418
419 =item $thr->error()
420
421 Threads are executed in an C<eval> context.  This method will return C<undef>
422 if the thread terminates I<normally>.  Otherwise, it returns the value of
423 C<$@> associated with the thread's execution status in its C<eval> context.
424
425 =item $thr->_handle()
426
427 This I<private> method returns a pointer (i.e., the memory location expressed
428 as an unsigned integer) to the internal thread structure associated with a
429 threads object.  For Win32, this is a pointer to the C<HANDLE> value returned
430 by C<CreateThread> (i.e., C<HANDLE *>); for other platforms, it is a pointer
431 to the C<pthread_t> structure used in the C<pthread_create> call (i.e.,
432 C<pthread_t *>).
433
434 This method is of no use for general Perl threads programming.  Its intent is
435 to provide other (XS-based) thread modules with the capability to access, and
436 possibly manipulate, the underlying thread structure associated with a Perl
437 thread.
438
439 =item threads->_handle()
440
441 Class method that allows a thread to obtain its own I<handle>.
442
443 =back
444
445 =head1 EXITING A THREAD
446
447 The usual method for terminating a thread is to
448 L<return()|perlfunc/"return EXPR"> from the entry point function with the
449 appropriate return value(s).
450
451 =over
452
453 =item threads->exit()
454
455 If needed, a thread can be exited at any time by calling
456 C<threads-E<gt>exit()>.  This will cause the thread to return C<undef> in a
457 scalar context, or the empty list in a list context.
458
459 When called from the I<main> thread, this behaves the same as C<exit(0)>.
460
461 =item threads->exit(status)
462
463 When called from a thread, this behaves like C<threads-E<gt>exit()> (i.e., the
464 exit status code is ignored).
465
466 When called from the I<main> thread, this behaves the same as C<exit(status)>.
467
468 =item die()
469
470 Calling C<die()> in a thread indicates an abnormal exit for the thread.  Any
471 C<$SIG{__DIE__}> handler in the thread will be called first, and then the
472 thread will exit with a warning message that will contain any arguments passed
473 in the C<die()> call.
474
475 =item exit(status)
476
477 Calling L<exit()|perlfunc/"exit EXPR"> inside a thread causes the whole
478 application to terminate.  Because of this, the use of C<exit()> inside
479 threaded code, or in modules that might be used in threaded applications, is
480 strongly discouraged.
481
482 If C<exit()> really is needed, then consider using the following:
483
484     threads->exit() if threads->can('exit');   # Thread friendly
485     exit(status);
486
487 =item use threads 'exit' => 'threads_only'
488
489 This globally overrides the default behavior of calling C<exit()> inside a
490 thread, and effectively causes such calls to behave the same as
491 C<threads-E<gt>exit()>.  In other words, with this setting, calling C<exit()>
492 causes only the thread to terminate.
493
494 Because of its global effect, this setting should not be used inside modules
495 or the like.
496
497 The I<main> thread is unaffected by this setting.
498
499 =item threads->create({'exit' => 'thread_only'}, ...)
500
501 This overrides the default behavior of C<exit()> inside the newly created
502 thread only.
503
504 =item $thr->set_thread_exit_only(boolean)
505
506 This can be used to change the I<exit thread only> behavior for a thread after
507 it has been created.  With a I<true> argument, C<exit()> will cause only the
508 thread to exit.  With a I<false> argument, C<exit()> will terminate the
509 application.
510
511 The I<main> thread is unaffected by this call.
512
513 =item threads->set_thread_exit_only(boolean)
514
515 Class method for use inside a thread to change its own behavior for C<exit()>.
516
517 The I<main> thread is unaffected by this call.
518
519 =back
520
521 =head1 THREAD STATE
522
523 The following boolean methods are useful in determining the I<state> of a
524 thread.
525
526 =over
527
528 =item $thr->is_running()
529
530 Returns true if a thread is still running (i.e., if its entry point function
531 has not yet finished or exited).
532
533 =item $thr->is_joinable()
534
535 Returns true if the thread has finished running, is not detached and has not
536 yet been joined.  In other words, the thread is ready to be joined, and a call
537 to C<$thr-E<gt>join()> will not I<block>.
538
539 =item $thr->is_detached()
540
541 Returns true if the thread has been detached.
542
543 =item threads->is_detached()
544
545 Class method that allows a thread to determine whether or not it is detached.
546
547 =back
548
549 =head1 THREAD CONTEXT
550
551 As with subroutines, the type of value returned from a thread's entry point
552 function may be determined by the thread's I<context>:  list, scalar or void.
553 The thread's context is determined at thread creation.  This is necessary so
554 that the context is available to the entry point function via
555 L<wantarray()|perlfunc/"wantarray">.  The thread may then specify a value of
556 the appropriate type to be returned from C<-E<gt>join()>.
557
558 =head2 Explicit context
559
560 Because thread creation and thread joining may occur in different contexts, it
561 may be desirable to state the context explicitly to the thread's entry point
562 function.  This may be done by calling C<-E<gt>create()> with a hash reference
563 as the first argument:
564
565     my $thr = threads->create({'context' => 'list'}, \&foo);
566     ...
567     my @results = $thr->join();
568
569 In the above, the threads object is returned to the parent thread in scalar
570 context, and the thread's entry point function C<foo> will be called in list
571 (array) context such that the parent thread can receive a list (array) from
572 the C<-E<gt>join()> call.  (C<'array'> is synonymous with C<'list'>.)
573
574 Similarly, if you need the threads object, but your thread will not be
575 returning a value (i.e., I<void> context), you would do the following:
576
577     my $thr = threads->create({'context' => 'void'}, \&foo);
578     ...
579     $thr->join();
580
581 The context type may also be used as the I<key> in the hash reference followed
582 by a I<true> value:
583
584     threads->create({'scalar' => 1}, \&foo);
585     ...
586     my ($thr) = threads->list();
587     my $result = $thr->join();
588
589 =head2 Implicit context
590
591 If not explicitly stated, the thread's context is implied from the context
592 of the C<-E<gt>create()> call:
593
594     # Create thread in list context
595     my ($thr) = threads->create(...);
596
597     # Create thread in scalar context
598     my $thr = threads->create(...);
599
600     # Create thread in void context
601     threads->create(...);
602
603 =head2 $thr->wantarray()
604
605 This returns the thread's context in the same manner as
606 L<wantarray()|perlfunc/"wantarray">.
607
608 =head2 threads->wantarray()
609
610 Class method to return the current thread's context.  This returns the same
611 value as running L<wantarray()|perlfunc/"wantarray"> inside the current
612 thread's entry point function.
613
614 =head1 THREAD STACK SIZE
615
616 The default per-thread stack size for different platforms varies
617 significantly, and is almost always far more than is needed for most
618 applications.  On Win32, Perl's makefile explicitly sets the default stack to
619 16 MB; on most other platforms, the system default is used, which again may be
620 much larger than is needed.
621
622 By tuning the stack size to more accurately reflect your application's needs,
623 you may significantly reduce your application's memory usage, and increase the
624 number of simultaneously running threads.
625
626 Note that on Windows, address space allocation granularity is 64 KB,
627 therefore, setting the stack smaller than that on Win32 Perl will not save any
628 more memory.
629
630 =over
631
632 =item threads->get_stack_size();
633
634 Returns the current default per-thread stack size.  The default is zero, which
635 means the system default stack size is currently in use.
636
637 =item $size = $thr->get_stack_size();
638
639 Returns the stack size for a particular thread.  A return value of zero
640 indicates the system default stack size was used for the thread.
641
642 =item $old_size = threads->set_stack_size($new_size);
643
644 Sets a new default per-thread stack size, and returns the previous setting.
645
646 Some platforms have a minimum thread stack size.  Trying to set the stack size
647 below this value will result in a warning, and the minimum stack size will be
648 used.
649
650 Some Linux platforms have a maximum stack size.  Setting too large of a stack
651 size will cause thread creation to fail.
652
653 If needed, C<$new_size> will be rounded up to the next multiple of the memory
654 page size (usually 4096 or 8192).
655
656 Threads created after the stack size is set will then either call
657 C<pthread_attr_setstacksize()> I<(for pthreads platforms)>, or supply the
658 stack size to C<CreateThread()> I<(for Win32 Perl)>.
659
660 (Obviously, this call does not affect any currently extant threads.)
661
662 =item use threads ('stack_size' => VALUE);
663
664 This sets the default per-thread stack size at the start of the application.
665
666 =item $ENV{'PERL5_ITHREADS_STACK_SIZE'}
667
668 The default per-thread stack size may be set at the start of the application
669 through the use of the environment variable C<PERL5_ITHREADS_STACK_SIZE>:
670
671     PERL5_ITHREADS_STACK_SIZE=1048576
672     export PERL5_ITHREADS_STACK_SIZE
673     perl -e'use threads; print(threads->get_stack_size(), "\n")'
674
675 This value overrides any C<stack_size> parameter given to C<use threads>.  Its
676 primary purpose is to permit setting the per-thread stack size for legacy
677 threaded applications.
678
679 =item threads->create({'stack_size' => VALUE}, FUNCTION, ARGS)
680
681 To specify a particular stack size for any individual thread, call
682 C<-E<gt>create()> with a hash reference as the first argument:
683
684     my $thr = threads->create({'stack_size' => 32*4096}, \&foo, @args);
685
686 =item $thr2 = $thr1->create(FUNCTION, ARGS)
687
688 This creates a new thread (C<$thr2>) that inherits the stack size from an
689 existing thread (C<$thr1>).  This is shorthand for the following:
690
691     my $stack_size = $thr1->get_stack_size();
692     my $thr2 = threads->create({'stack_size' => $stack_size}, FUNCTION, ARGS);
693
694 =back
695
696 =head1 THREAD SIGNALLING
697
698 When safe signals is in effect (the default behavior - see L</"Unsafe signals">
699 for more details), then signals may be sent and acted upon by individual
700 threads.
701
702 =over 4
703
704 =item $thr->kill('SIG...');
705
706 Sends the specified signal to the thread.  Signal names and (positive) signal
707 numbers are the same as those supported by
708 L<kill()|perlfunc/"kill SIGNAL, LIST">.  For example, 'SIGTERM', 'TERM' and
709 (depending on the OS) 15 are all valid arguments to C<-E<gt>kill()>.
710
711 Returns the thread object to allow for method chaining:
712
713     $thr->kill('SIG...')->join();
714
715 =back
716
717 Signal handlers need to be set up in the threads for the signals they are
718 expected to act upon.  Here's an example for I<cancelling> a thread:
719
720     use threads;
721
722     sub thr_func
723     {
724         # Thread 'cancellation' signal handler
725         $SIG{'KILL'} = sub { threads->exit(); };
726
727         ...
728     }
729
730     # Create a thread
731     my $thr = threads->create('thr_func');
732
733     ...
734
735     # Signal the thread to terminate, and then detach
736     # it so that it will get cleaned up automatically
737     $thr->kill('KILL')->detach();
738
739 Here's another simplistic example that illustrates the use of thread
740 signalling in conjunction with a semaphore to provide rudimentary I<suspend>
741 and I<resume> capabilities:
742
743     use threads;
744     use Thread::Semaphore;
745
746     sub thr_func
747     {
748         my $sema = shift;
749
750         # Thread 'suspend/resume' signal handler
751         $SIG{'STOP'} = sub {
752             $sema->down();      # Thread suspended
753             $sema->up();        # Thread resumes
754         };
755
756         ...
757     }
758
759     # Create a semaphore and pass it to a thread
760     my $sema = Thread::Semaphore->new();
761     my $thr = threads->create('thr_func', $sema);
762
763     # Suspend the thread
764     $sema->down();
765     $thr->kill('STOP');
766
767     ...
768
769     # Allow the thread to continue
770     $sema->up();
771
772 CAVEAT:  The thread signalling capability provided by this module does not
773 actually send signals via the OS.  It I<emulates> signals at the Perl-level
774 such that signal handlers are called in the appropriate thread.  For example,
775 sending C<$thr-E<gt>kill('STOP')> does not actually suspend a thread (or the
776 whole process), but does cause a C<$SIG{'STOP'}> handler to be called in that
777 thread (as illustrated above).
778
779 As such, signals that would normally not be appropriate to use in the
780 C<kill()> command (e.g., C<kill('KILL', $$)>) are okay to use with the
781 C<-E<gt>kill()> method (again, as illustrated above).
782
783 Correspondingly, sending a signal to a thread does not disrupt the operation
784 the thread is currently working on:  The signal will be acted upon after the
785 current operation has completed.  For instance, if the thread is I<stuck> on
786 an I/O call, sending it a signal will not cause the I/O call to be interrupted
787 such that the signal is acted up immediately.
788
789 Sending a signal to a terminated/finished thread is ignored.
790
791 =head1 WARNINGS
792
793 =over 4
794
795 =item Perl exited with active threads:
796
797 If the program exits without all threads having either been joined or
798 detached, then this warning will be issued.
799
800 NOTE:  If the I<main> thread exits, then this warning cannot be suppressed
801 using C<no warnings 'threads';> as suggested below.
802
803 =item Thread creation failed: pthread_create returned #
804
805 See the appropriate I<man> page for C<pthread_create> to determine the actual
806 cause for the failure.
807
808 =item Thread # terminated abnormally: ...
809
810 A thread terminated in some manner other than just returning from its entry
811 point function, or by using C<threads-E<gt>exit()>.  For example, the thread
812 may have terminated because of an error, or by using C<die>.
813
814 =item Using minimum thread stack size of #
815
816 Some platforms have a minimum thread stack size.  Trying to set the stack size
817 below this value will result in the above warning, and the stack size will be
818 set to the minimum.
819
820 =item Thread creation failed: pthread_attr_setstacksize(I<SIZE>) returned 22
821
822 The specified I<SIZE> exceeds the system's maximum stack size.  Use a smaller
823 value for the stack size.
824
825 =back
826
827 If needed, thread warnings can be suppressed by using:
828
829     no warnings 'threads';
830
831 in the appropriate scope.
832
833 =head1 ERRORS
834
835 =over 4
836
837 =item This Perl not built to support threads
838
839 The particular copy of Perl that you're trying to use was not built using the
840 C<useithreads> configuration option.
841
842 Having threads support requires all of Perl and all of the XS modules in the
843 Perl installation to be rebuilt; it is not just a question of adding the
844 L<threads> module (i.e., threaded and non-threaded Perls are binary
845 incompatible).
846
847 =item Cannot change stack size of an existing thread
848
849 The stack size of currently extant threads cannot be changed, therefore, the
850 following results in the above error:
851
852     $thr->set_stack_size($size);
853
854 =item Cannot signal threads without safe signals
855
856 Safe signals must be in effect to use the C<-E<gt>kill()> signalling method.
857 See L</"Unsafe signals"> for more details.
858
859 =item Unrecognized signal name: ...
860
861 The particular copy of Perl that you're trying to use does not support the
862 specified signal being used in a C<-E<gt>kill()> call.
863
864 =back
865
866 =head1 BUGS AND LIMITATIONS
867
868 Before you consider posting a bug report, please consult, and possibly post a
869 message to the discussion forum to see if what you've encountered is a known
870 problem.
871
872 =over
873
874 =item Thread-safe modules
875
876 See L<perlmod/"Making your module threadsafe"> when creating modules that may
877 be used in threaded applications, especially if those modules use non-Perl
878 data, or XS code.
879
880 =item Using non-thread-safe modules
881
882 Unfortunately, you may encounter Perl modules that are not I<thread-safe>.
883 For example, they may crash the Perl interpreter during execution, or may dump
884 core on termination.  Depending on the module and the requirements of your
885 application, it may be possible to work around such difficulties.
886
887 If the module will only be used inside a thread, you can try loading the
888 module from inside the thread entry point function using C<require> (and
889 C<import> if needed):
890
891     sub thr_func
892     {
893         require Unsafe::Module
894         # Unsafe::Module->import(...);
895
896         ....
897     }
898
899 If the module is needed inside the I<main> thread, try modifying your
900 application so that the module is loaded (again using C<require> and
901 C<-E<gt>import()>) after any threads are started, and in such a way that no
902 other threads are started afterwards.
903
904 If the above does not work, or is not adequate for your application, then file
905 a bug report on L<http://rt.cpan.org/Public/> against the problematic module.
906
907 =item Memory consumption
908
909 On most systems, frequent and continual creation and destruction of threads
910 can lead to ever-increasing growth in the memory footprint of the Perl
911 interpreter.  While it is simple to just launch threads and then
912 C<-E<gt>join()> or C<-E<gt>detach()> them, for long-lived applications, it is
913 better to maintain a pool of threads, and to reuse them for the work needed,
914 using L<queues|Thread::Queue> to notify threads of pending work.  The CPAN
915 distribution of this module contains a simple example
916 (F<examples/pool_reuse.pl>) illustrating the creation, use and monitoring of a
917 pool of I<reusable> threads.
918
919 =item Current working directory
920
921 On all platforms except MSWin32, the setting for the current working directory
922 is shared among all threads such that changing it in one thread (e.g., using
923 C<chdir()>) will affect all the threads in the application.
924
925 On MSWin32, each thread maintains its own the current working directory
926 setting.
927
928 =item Environment variables
929
930 Currently, on all platforms except MSWin32, all I<system> calls (e.g., using
931 C<system()> or back-ticks) made from threads use the environment variable
932 settings from the I<main> thread.  In other words, changes made to C<%ENV> in
933 a thread will not be visible in I<system> calls made by that thread.
934
935 To work around this, set environment variables as part of the I<system> call.
936 For example:
937
938     my $msg = 'hello';
939     system("FOO=$msg; echo \$FOO");   # Outputs 'hello' to STDOUT
940
941 On MSWin32, each thread maintains its own set of environment variables.
942
943 =item Catching signals
944
945 Signals are I<caught> by the main thread (thread ID = 0) of a script.
946 Therefore, setting up signal handlers in threads for purposes other than
947 L</"THREAD SIGNALLING"> as documented above will not accomplish what is
948 intended.
949
950 This is especially true if trying to catch C<SIGALRM> in a thread.  To handle
951 alarms in threads, set up a signal handler in the main thread, and then use
952 L</"THREAD SIGNALLING"> to relay the signal to the thread:
953
954   # Create thread with a task that may time out
955   my $thr = threads->create(sub {
956       threads->yield();
957       eval {
958           $SIG{ALRM} = sub { die("Timeout\n"); };
959           alarm(10);
960           ...  # Do work here
961           alarm(0);
962       };
963       if ($@ =~ /Timeout/) {
964           warn("Task in thread timed out\n");
965       }
966   };
967
968   # Set signal handler to relay SIGALRM to thread
969   $SIG{ALRM} = sub { $thr->kill('ALRM') };
970
971   ... # Main thread continues working
972
973 =item Parent-child threads
974
975 On some platforms, it might not be possible to destroy I<parent> threads while
976 there are still existing I<child> threads.
977
978 =item Creating threads inside special blocks
979
980 Creating threads inside C<BEGIN>, C<CHECK> or C<INIT> blocks should not be
981 relied upon.  Depending on the Perl version and the application code, results
982 may range from success, to (apparently harmless) warnings of leaked scalar, or
983 all the way up to crashing of the Perl interpreter.
984
985 =item Unsafe signals
986
987 Since Perl 5.8.0, signals have been made safer in Perl by postponing their
988 handling until the interpreter is in a I<safe> state.  See
989 L<perl58delta/"Safe Signals"> and L<perlipc/"Deferred Signals (Safe Signals)">
990 for more details.
991
992 Safe signals is the default behavior, and the old, immediate, unsafe
993 signalling behavior is only in effect in the following situations:
994
995 =over 4
996
997 =item * Perl has been built with C<PERL_OLD_SIGNALS> (see C<perl -V>).
998
999 =item * The environment variable C<PERL_SIGNALS> is set to C<unsafe> (see L<perlrun/"PERL_SIGNALS">).
1000
1001 =item * The module L<Perl::Unsafe::Signals> is used.
1002
1003 =back
1004
1005 If unsafe signals is in effect, then signal handling is not thread-safe, and
1006 the C<-E<gt>kill()> signalling method cannot be used.
1007
1008 =item Returning closures from threads
1009
1010 Returning closures from threads should not be relied upon.  Depending on the
1011 Perl version and the application code, results may range from success, to
1012 (apparently harmless) warnings of leaked scalar, or all the way up to crashing
1013 of the Perl interpreter.
1014
1015 =item Returning objects from threads
1016
1017 Returning objects from threads does not work.  Depending on the classes
1018 involved, you may be able to work around this by returning a serialized
1019 version of the object (e.g., using L<Data::Dumper> or L<Storable>), and then
1020 reconstituting it in the joining thread.  If you're using Perl 5.10.0 or
1021 later, and if the class supports L<shared objects|threads::shared/"OBJECTS">,
1022 you can pass them via L<shared queues|Thread::Queue>.
1023
1024 =item END blocks in threads
1025
1026 It is possible to add L<END blocks|perlmod/"BEGIN, UNITCHECK, CHECK, INIT and
1027 END"> to threads by using L<require|perlfunc/"require VERSION"> or
1028 L<eval|perlfunc/"eval EXPR"> with the appropriate code.  These C<END> blocks
1029 will then be executed when the thread's interpreter is destroyed (i.e., either
1030 during a C<-E<gt>join()> call, or at program termination).
1031
1032 However, calling any L<threads> methods in such an C<END> block will most
1033 likely I<fail> (e.g., the application may hang, or generate an error) due to
1034 mutexes that are needed to control functionality within the L<threads> module.
1035
1036 For this reason, the use of C<END> blocks in threads is B<strongly>
1037 discouraged.
1038
1039 =item Open directory handles
1040
1041 In perl 5.14 and higher, on systems other than Windows that do
1042 not support the C<fchdir> C function, directory handles (see
1043 L<opendir|perlfunc/"opendir DIRHANDLE,EXPR">) will not be copied to new
1044 threads. You can use the C<d_fchdir> variable in L<Config.pm|Config> to
1045 determine whether your system supports it.
1046
1047 In prior perl versions, spawning threads with open directory handles would
1048 crash the interpreter.
1049 L<[perl #75154]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=75154>
1050
1051 =item Perl Bugs and the CPAN Version of L<threads>
1052
1053 Support for threads extends beyond the code in this module (i.e.,
1054 F<threads.pm> and F<threads.xs>), and into the Perl interpreter itself.  Older
1055 versions of Perl contain bugs that may manifest themselves despite using the
1056 latest version of L<threads> from CPAN.  There is no workaround for this other
1057 than upgrading to the latest version of Perl.
1058
1059 Even with the latest version of Perl, it is known that certain constructs
1060 with threads may result in warning messages concerning leaked scalars or
1061 unreferenced scalars.  However, such warnings are harmless, and may safely be
1062 ignored.
1063
1064 You can search for L<threads> related bug reports at
1065 L<http://rt.cpan.org/Public/>.  If needed submit any new bugs, problems,
1066 patches, etc. to: L<http://rt.cpan.org/Public/Dist/Display.html?Name=threads>
1067
1068 =back
1069
1070 =head1 REQUIREMENTS
1071
1072 Perl 5.8.0 or later
1073
1074 =head1 SEE ALSO
1075
1076 L<threads> Discussion Forum on CPAN:
1077 L<http://www.cpanforum.com/dist/threads>
1078
1079 L<threads::shared>, L<perlthrtut>
1080
1081 L<http://www.perl.com/pub/a/2002/06/11/threads.html> and
1082 L<http://www.perl.com/pub/a/2002/09/04/threads.html>
1083
1084 Perl threads mailing list:
1085 L<http://lists.perl.org/list/ithreads.html>
1086
1087 Stack size discussion:
1088 L<http://www.perlmonks.org/?node_id=532956>
1089
1090 =head1 AUTHOR
1091
1092 Artur Bergman E<lt>sky AT crucially DOT netE<gt>
1093
1094 CPAN version produced by Jerry D. Hedden <jdhedden AT cpan DOT org>
1095
1096 =head1 LICENSE
1097
1098 threads is released under the same license as Perl.
1099
1100 =head1 ACKNOWLEDGEMENTS
1101
1102 Richard Soderberg E<lt>perl AT crystalflame DOT netE<gt> -
1103 Helping me out tons, trying to find reasons for races and other weird bugs!
1104
1105 Simon Cozens E<lt>simon AT brecon DOT co DOT ukE<gt> -
1106 Being there to answer zillions of annoying questions
1107
1108 Rocco Caputo E<lt>troc AT netrus DOT netE<gt>
1109
1110 Vipul Ved Prakash E<lt>mail AT vipul DOT netE<gt> -
1111 Helping with debugging
1112
1113 Dean Arnold E<lt>darnold AT presicient DOT comE<gt> -
1114 Stack size API
1115
1116 =cut