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