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