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