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