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