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