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