This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Appease the gods of stupid tests.
[perl5.git] / dist / threads / lib / threads.pm
CommitLineData
47ba8780
AB
1package threads;
2
32419a4c 3use 5.008;
fcea4b7c 4
47ba8780
AB
5use strict;
6use warnings;
73e09c8f 7
e094d663 8our $VERSION = '2.04';
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
aa8d754d 137This document describes threads version 2.02
47ba8780 138
10a45977
RS
139=head1 WARNING
140
141The "interpreter-based threads" provided by Perl are not the fast, lightweight
142system for multitasking that one might expect or hope for. Threads are
143implemented in a way that make them easy to misuse. Few people know how to
144use them correctly or will be able to provide help.
145
146The use of interpreter-based threads in perl is officially
147L<discouraged|perlpolicy/discouraged>.
148
47ba8780
AB
149=head1 SYNOPSIS
150
3ab14376
JH
151 use threads ('yield',
152 'stack_size' => 64*4096,
153 'exit' => 'threads_only',
154 'stringify');
47ba8780 155
38875929 156 sub start_thread {
0f1612a7 157 my @args = @_;
9d9ff5b1 158 print('Thread started: ', join(' ', @args), "\n");
38875929 159 }
fea7688c
JH
160 my $thr = threads->create('start_thread', 'argument');
161 $thr->join();
0f1612a7
JH
162
163 threads->create(sub { print("I am a thread\n"); })->join();
47ba8780 164
fea7688c
JH
165 my $thr2 = async { foreach (@files) { ... } };
166 $thr2->join();
955c272e
JH
167 if (my $err = $thr2->error()) {
168 warn("Thread error: $err\n");
169 }
0f1612a7 170
9d9ff5b1 171 # Invoke thread in list context (implicit) so it can return a list
0f1612a7 172 my ($thr) = threads->create(sub { return (qw/a b c/); });
9d9ff5b1
JH
173 # or specify list context explicitly
174 my $thr = threads->create({'context' => 'list'},
175 sub { return (qw/a b c/); });
0f1612a7 176 my @results = $thr->join();
47ba8780 177
fea7688c 178 $thr->detach();
47ba8780 179
69a9b4b8 180 # Get a thread's object
fea7688c
JH
181 $thr = threads->self();
182 $thr = threads->object($tid);
11c51ed3 183
69a9b4b8 184 # Get a thread's ID
0f1612a7 185 $tid = threads->tid();
fea7688c 186 $tid = $thr->tid();
3ab14376 187 $tid = "$thr";
47ba8780 188
69a9b4b8 189 # Give other threads a chance to run
38875929 190 threads->yield();
0f1612a7
JH
191 yield();
192
69a9b4b8 193 # Lists of non-detached threads
0f1612a7 194 my @threads = threads->list();
fcea4b7c 195 my $thread_count = threads->list();
f9dff5f5 196
ead32952
JH
197 my @running = threads->list(threads::running);
198 my @joinable = threads->list(threads::joinable);
199
69a9b4b8 200 # Test thread objects
0f1612a7
JH
201 if ($thr1 == $thr2) {
202 ...
203 }
678a9b6c 204
69a9b4b8 205 # Manage thread stack size
514612b7
JH
206 $stack_size = threads->get_stack_size();
207 $old_size = threads->set_stack_size(32*4096);
208
9d9ff5b1
JH
209 # Create a thread with a specific context and stack size
210 my $thr = threads->create({ 'context' => 'list',
69a9b4b8
RGS
211 'stack_size' => 32*4096,
212 'exit' => 'thread_only' },
9d9ff5b1 213 \&foo);
ead32952
JH
214
215 # Get thread's context
216 my $wantarray = $thr->wantarray();
217
218 # Check thread's state
219 if ($thr->is_running()) {
220 sleep(1);
221 }
222 if ($thr->is_joinable()) {
223 $thr->join();
224 }
9d9ff5b1 225
69a9b4b8 226 # Send a signal to a thread
c0003851
JH
227 $thr->kill('SIGUSR1');
228
69a9b4b8 229 # Exit a thread
4dcb9e53
JH
230 threads->exit();
231
47ba8780
AB
232=head1 DESCRIPTION
233
3350824e
JH
234Since Perl 5.8, thread programming has been available using a model called
235I<interpreter threads> which provides a new Perl interpreter for each
236thread, and, by default, results in no data or state information being shared
237between threads.
11c51ed3 238
3350824e
JH
239(Prior to Perl 5.8, I<5005threads> was available through the C<Thread.pm> API.
240This threading model has been deprecated, and was removed as of Perl 5.10.0.)
11c51ed3 241
3350824e
JH
242As just mentioned, all variables are, by default, thread local. To use shared
243variables, you need to also load L<threads::shared>:
6ebc233e
RGS
244
245 use threads;
246 use threads::shared;
11c51ed3 247
3350824e
JH
248When loading L<threads::shared>, you must C<use threads> before you
249C<use threads::shared>. (C<threads> will emit a warning if you do it the
250other way around.)
251
252It is strongly recommended that you enable threads via C<use threads> as early
253as possible in your script.
254
255If needed, scripts can be written so as to run on both threaded and
256non-threaded Perls:
257
258 my $can_use_threads = eval 'use threads; 1';
259 if ($can_use_threads) {
260 # Do processing using threads
261 ...
262 } else {
263 # Do it without using threads
264 ...
265 }
47ba8780
AB
266
267=over
268
0f1612a7 269=item $thr = threads->create(FUNCTION, ARGS)
47ba8780 270
0f1612a7
JH
271This will create a new thread that will begin execution with the specified
272entry point function, and give it the I<ARGS> list as parameters. It will
273return the corresponding threads object, or C<undef> if thread creation failed.
47ba8780 274
0f1612a7
JH
275I<FUNCTION> may either be the name of a function, an anonymous subroutine, or
276a code ref.
47ba8780 277
0f1612a7
JH
278 my $thr = threads->create('func_name', ...);
279 # or
280 my $thr = threads->create(sub { ... }, ...);
281 # or
282 my $thr = threads->create(\&func, ...);
93512b4d 283
0f1612a7
JH
284The C<-E<gt>new()> method is an alias for C<-E<gt>create()>.
285
286=item $thr->join()
287
288This will wait for the corresponding thread to complete its execution. When
289the thread finishes, C<-E<gt>join()> will return the return value(s) of the
290entry point function.
291
9d9ff5b1
JH
292The context (void, scalar or list) for the return value(s) for C<-E<gt>join()>
293is determined at the time of thread creation.
0f1612a7 294
9d9ff5b1 295 # Create thread in list context (implicit)
0f1612a7
JH
296 my ($thr1) = threads->create(sub {
297 my @results = qw(a b c);
298 return (@results);
9d9ff5b1
JH
299 });
300 # or (explicit)
301 my $thr1 = threads->create({'context' => 'list'},
302 sub {
303 my @results = qw(a b c);
304 return (@results);
305 });
0f1612a7
JH
306 # Retrieve list results from thread
307 my @res1 = $thr1->join();
308
9d9ff5b1 309 # Create thread in scalar context (implicit)
0f1612a7
JH
310 my $thr2 = threads->create(sub {
311 my $result = 42;
312 return ($result);
9d9ff5b1 313 });
0f1612a7
JH
314 # Retrieve scalar result from thread
315 my $res2 = $thr2->join();
316
9d9ff5b1
JH
317 # Create a thread in void context (explicit)
318 my $thr3 = threads->create({'void' => 1},
319 sub { print("Hello, world\n"); });
320 # Join the thread in void context (i.e., no return value)
321 $thr3->join();
322
323See L</"THREAD CONTEXT"> for more details.
324
4dcb9e53
JH
325If the program exits without all threads having either been joined or
326detached, then a warning will be issued.
93512b4d 327
fcea4b7c
JH
328Calling C<-E<gt>join()> or C<-E<gt>detach()> on an already joined thread will
329cause an error to be thrown.
47ba8780 330
fcea4b7c 331=item $thr->detach()
47ba8780 332
fcea4b7c 333Makes the thread unjoinable, and causes any eventual return value to be
4dcb9e53
JH
334discarded. When the program exits, any detached threads that are still
335running are silently terminated.
336
337If the program exits without all threads having either been joined or
338detached, then a warning will be issued.
fcea4b7c
JH
339
340Calling C<-E<gt>join()> or C<-E<gt>detach()> on an already detached thread
341will cause an error to be thrown.
0f1612a7
JH
342
343=item threads->detach()
344
345Class method that allows a thread to detach itself.
346
fcea4b7c 347=item threads->self()
47ba8780 348
fcea4b7c 349Class method that allows a thread to obtain its own I<threads> object.
47ba8780 350
0f1612a7
JH
351=item $thr->tid()
352
353Returns the ID of the thread. Thread IDs are unique integers with the main
354thread in a program being 0, and incrementing by 1 for every thread created.
47ba8780 355
0f1612a7 356=item threads->tid()
38875929 357
0f1612a7 358Class method that allows a thread to obtain its own ID.
47ba8780 359
3ab14376
JH
360=item "$thr"
361
362If you add the C<stringify> import option to your C<use threads> declaration,
363then using a threads object in a string or a string context (e.g., as a hash
364key) will cause its ID to be used as the value:
365
5c6ff896 366 use threads qw(stringify);
3ab14376 367
5c6ff896
JH
368 my $thr = threads->create(...);
369 print("Thread $thr started...\n"); # Prints out: Thread 1 started...
3ab14376 370
0f1612a7 371=item threads->object($tid)
8c9849ff 372
0f1612a7 373This will return the I<threads> object for the I<active> thread associated
b91a79b9
SM
374with the specified thread ID. If C<$tid> is the value for the current thread,
375then this call works the same as C<-E<gt>self()>. Otherwise, returns C<undef>
376if there is no thread associated with the TID, if the thread is joined or
377detached, if no TID is specified or if the specified TID is undef.
8c9849ff 378
fcea4b7c 379=item threads->yield()
f9dff5f5 380
38875929
DM
381This is a suggestion to the OS to let this thread yield CPU time to other
382threads. What actually happens is highly dependent upon the underlying
383thread implementation.
f9dff5f5 384
fcea4b7c 385You may do C<use threads qw(yield)>, and then just use C<yield()> in your
70f2e746
DM
386code.
387
f4cc38af 388=item threads->list()
678a9b6c 389
ead32952
JH
390=item threads->list(threads::all)
391
392=item threads->list(threads::running)
393
394=item threads->list(threads::joinable)
395
396With no arguments (or using C<threads::all>) and in a list context, returns a
397list of all non-joined, non-detached I<threads> objects. In a scalar context,
398returns a count of the same.
399
400With a I<true> argument (using C<threads::running>), returns a list of all
8718f9a1 401non-joined, non-detached I<threads> objects that are still running.
ead32952
JH
402
403With a I<false> argument (using C<threads::joinable>), returns a list of all
404non-joined, non-detached I<threads> objects that have finished running (i.e.,
405for which C<-E<gt>join()> will not I<block>).
678a9b6c 406
0f1612a7
JH
407=item $thr1->equal($thr2)
408
409Tests if two threads objects are the same thread or not. This is overloaded
fcea4b7c 410to the more natural forms:
0f1612a7
JH
411
412 if ($thr1 == $thr2) {
413 print("Threads are the same\n");
414 }
fcea4b7c
JH
415 # or
416 if ($thr1 != $thr2) {
417 print("Threads differ\n");
418 }
0f1612a7
JH
419
420(Thread comparison is based on thread IDs.)
421
386c44e5
AB
422=item async BLOCK;
423
424C<async> creates a thread to execute the block immediately following
fcea4b7c 425it. This block is treated as an anonymous subroutine, and so must have a
5cbb7319 426semicolon after the closing brace. Like C<threads-E<gt>create()>, C<async>
fcea4b7c 427returns a I<threads> object.
386c44e5 428
955c272e
JH
429=item $thr->error()
430
431Threads are executed in an C<eval> context. This method will return C<undef>
432if the thread terminates I<normally>. Otherwise, it returns the value of
433C<$@> associated with the thread's execution status in its C<eval> context.
434
f4cc38af
JH
435=item $thr->_handle()
436
afb37b32
JH
437This I<private> method returns a pointer (i.e., the memory location expressed
438as an unsigned integer) to the internal thread structure associated with a
439threads object. For Win32, this is a pointer to the C<HANDLE> value returned
440by C<CreateThread> (i.e., C<HANDLE *>); for other platforms, it is a pointer
441to the C<pthread_t> structure used in the C<pthread_create> call (i.e.,
442C<pthread_t *>).
f4cc38af
JH
443
444This method is of no use for general Perl threads programming. Its intent is
445to provide other (XS-based) thread modules with the capability to access, and
446possibly manipulate, the underlying thread structure associated with a Perl
447thread.
448
449=item threads->_handle()
450
451Class method that allows a thread to obtain its own I<handle>.
452
47ba8780
AB
453=back
454
69a9b4b8
RGS
455=head1 EXITING A THREAD
456
457The usual method for terminating a thread is to
458L<return()|perlfunc/"return EXPR"> from the entry point function with the
459appropriate return value(s).
460
461=over
462
463=item threads->exit()
464
465If needed, a thread can be exited at any time by calling
466C<threads-E<gt>exit()>. This will cause the thread to return C<undef> in a
467scalar context, or the empty list in a list context.
468
469When called from the I<main> thread, this behaves the same as C<exit(0)>.
470
471=item threads->exit(status)
472
473When called from a thread, this behaves like C<threads-E<gt>exit()> (i.e., the
474exit status code is ignored).
475
476When called from the I<main> thread, this behaves the same as C<exit(status)>.
477
478=item die()
479
480Calling C<die()> in a thread indicates an abnormal exit for the thread. Any
481C<$SIG{__DIE__}> handler in the thread will be called first, and then the
482thread will exit with a warning message that will contain any arguments passed
483in the C<die()> call.
484
485=item exit(status)
486
487Calling L<exit()|perlfunc/"exit EXPR"> inside a thread causes the whole
488application to terminate. Because of this, the use of C<exit()> inside
489threaded code, or in modules that might be used in threaded applications, is
490strongly discouraged.
491
492If C<exit()> really is needed, then consider using the following:
493
60bd5ef6 494 threads->exit() if threads->can('exit'); # Thread friendly
69a9b4b8
RGS
495 exit(status);
496
5cbb7319 497=item use threads 'exit' => 'threads_only'
69a9b4b8
RGS
498
499This globally overrides the default behavior of calling C<exit()> inside a
500thread, and effectively causes such calls to behave the same as
501C<threads-E<gt>exit()>. In other words, with this setting, calling C<exit()>
502causes only the thread to terminate.
503
504Because of its global effect, this setting should not be used inside modules
505or the like.
506
507The I<main> thread is unaffected by this setting.
508
509=item threads->create({'exit' => 'thread_only'}, ...)
510
511This overrides the default behavior of C<exit()> inside the newly created
512thread only.
513
514=item $thr->set_thread_exit_only(boolean)
515
516This can be used to change the I<exit thread only> behavior for a thread after
5cbb7319
RGS
517it has been created. With a I<true> argument, C<exit()> will cause only the
518thread to exit. With a I<false> argument, C<exit()> will terminate the
69a9b4b8
RGS
519application.
520
521The I<main> thread is unaffected by this call.
522
523=item threads->set_thread_exit_only(boolean)
524
5cbb7319 525Class method for use inside a thread to change its own behavior for C<exit()>.
69a9b4b8
RGS
526
527The I<main> thread is unaffected by this call.
528
529=back
530
ead32952
JH
531=head1 THREAD STATE
532
533The following boolean methods are useful in determining the I<state> of a
534thread.
535
536=over
537
538=item $thr->is_running()
539
540Returns true if a thread is still running (i.e., if its entry point function
5cbb7319 541has not yet finished or exited).
ead32952
JH
542
543=item $thr->is_joinable()
544
545Returns true if the thread has finished running, is not detached and has not
5cbb7319
RGS
546yet been joined. In other words, the thread is ready to be joined, and a call
547to C<$thr-E<gt>join()> will not I<block>.
ead32952
JH
548
549=item $thr->is_detached()
550
551Returns true if the thread has been detached.
552
553=item threads->is_detached()
554
555Class method that allows a thread to determine whether or not it is detached.
556
557=back
558
9d9ff5b1
JH
559=head1 THREAD CONTEXT
560
561As with subroutines, the type of value returned from a thread's entry point
562function may be determined by the thread's I<context>: list, scalar or void.
563The thread's context is determined at thread creation. This is necessary so
564that the context is available to the entry point function via
206f4df7 565L<wantarray()|perlfunc/"wantarray">. The thread may then specify a value of
9d9ff5b1
JH
566the appropriate type to be returned from C<-E<gt>join()>.
567
568=head2 Explicit context
569
570Because thread creation and thread joining may occur in different contexts, it
571may be desirable to state the context explicitly to the thread's entry point
5cbb7319 572function. This may be done by calling C<-E<gt>create()> with a hash reference
9d9ff5b1
JH
573as the first argument:
574
575 my $thr = threads->create({'context' => 'list'}, \&foo);
576 ...
577 my @results = $thr->join();
578
579In the above, the threads object is returned to the parent thread in scalar
580context, and the thread's entry point function C<foo> will be called in list
da140a40
JH
581(array) context such that the parent thread can receive a list (array) from
582the C<-E<gt>join()> call. (C<'array'> is synonymous with C<'list'>.)
583
584Similarly, if you need the threads object, but your thread will not be
9d9ff5b1
JH
585returning a value (i.e., I<void> context), you would do the following:
586
587 my $thr = threads->create({'context' => 'void'}, \&foo);
588 ...
589 $thr->join();
590
5cbb7319 591The context type may also be used as the I<key> in the hash reference followed
9d9ff5b1
JH
592by a I<true> value:
593
594 threads->create({'scalar' => 1}, \&foo);
595 ...
596 my ($thr) = threads->list();
597 my $result = $thr->join();
598
599=head2 Implicit context
600
601If not explicitly stated, the thread's context is implied from the context
602of the C<-E<gt>create()> call:
603
604 # Create thread in list context
605 my ($thr) = threads->create(...);
606
607 # Create thread in scalar context
608 my $thr = threads->create(...);
609
610 # Create thread in void context
611 threads->create(...);
612
ead32952
JH
613=head2 $thr->wantarray()
614
615This returns the thread's context in the same manner as
616L<wantarray()|perlfunc/"wantarray">.
617
618=head2 threads->wantarray()
619
5cbb7319
RGS
620Class method to return the current thread's context. This returns the same
621value as running L<wantarray()|perlfunc/"wantarray"> inside the current
622thread's entry point function.
ead32952 623
514612b7
JH
624=head1 THREAD STACK SIZE
625
626The default per-thread stack size for different platforms varies
627significantly, and is almost always far more than is needed for most
628applications. On Win32, Perl's makefile explicitly sets the default stack to
62916 MB; on most other platforms, the system default is used, which again may be
630much larger than is needed.
631
632By tuning the stack size to more accurately reflect your application's needs,
633you may significantly reduce your application's memory usage, and increase the
634number of simultaneously running threads.
635
5cbb7319
RGS
636Note that on Windows, address space allocation granularity is 64 KB,
637therefore, setting the stack smaller than that on Win32 Perl will not save any
638more memory.
514612b7
JH
639
640=over
641
642=item threads->get_stack_size();
643
644Returns the current default per-thread stack size. The default is zero, which
645means the system default stack size is currently in use.
646
647=item $size = $thr->get_stack_size();
648
649Returns the stack size for a particular thread. A return value of zero
650indicates the system default stack size was used for the thread.
651
652=item $old_size = threads->set_stack_size($new_size);
653
654Sets a new default per-thread stack size, and returns the previous setting.
655
656Some platforms have a minimum thread stack size. Trying to set the stack size
657below this value will result in a warning, and the minimum stack size will be
658used.
659
660Some Linux platforms have a maximum stack size. Setting too large of a stack
661size will cause thread creation to fail.
662
663If needed, C<$new_size> will be rounded up to the next multiple of the memory
664page size (usually 4096 or 8192).
665
666Threads created after the stack size is set will then either call
667C<pthread_attr_setstacksize()> I<(for pthreads platforms)>, or supply the
668stack size to C<CreateThread()> I<(for Win32 Perl)>.
669
670(Obviously, this call does not affect any currently extant threads.)
671
672=item use threads ('stack_size' => VALUE);
673
674This sets the default per-thread stack size at the start of the application.
675
676=item $ENV{'PERL5_ITHREADS_STACK_SIZE'}
677
678The default per-thread stack size may be set at the start of the application
679through the use of the environment variable C<PERL5_ITHREADS_STACK_SIZE>:
680
681 PERL5_ITHREADS_STACK_SIZE=1048576
682 export PERL5_ITHREADS_STACK_SIZE
683 perl -e'use threads; print(threads->get_stack_size(), "\n")'
684
685This value overrides any C<stack_size> parameter given to C<use threads>. Its
686primary purpose is to permit setting the per-thread stack size for legacy
687threaded applications.
688
689=item threads->create({'stack_size' => VALUE}, FUNCTION, ARGS)
690
5cbb7319
RGS
691To specify a particular stack size for any individual thread, call
692C<-E<gt>create()> with a hash reference as the first argument:
9d9ff5b1
JH
693
694 my $thr = threads->create({'stack_size' => 32*4096}, \&foo, @args);
514612b7
JH
695
696=item $thr2 = $thr1->create(FUNCTION, ARGS)
697
698This creates a new thread (C<$thr2>) that inherits the stack size from an
699existing thread (C<$thr1>). This is shorthand for the following:
700
701 my $stack_size = $thr1->get_stack_size();
702 my $thr2 = threads->create({'stack_size' => $stack_size}, FUNCTION, ARGS);
703
704=back
705
c0003851
JH
706=head1 THREAD SIGNALLING
707
9d9ff5b1 708When safe signals is in effect (the default behavior - see L</"Unsafe signals">
1152d448
JH
709for more details), then signals may be sent and acted upon by individual
710threads.
c0003851
JH
711
712=over 4
713
714=item $thr->kill('SIG...');
715
716Sends the specified signal to the thread. Signal names and (positive) signal
717numbers are the same as those supported by
718L<kill()|perlfunc/"kill SIGNAL, LIST">. For example, 'SIGTERM', 'TERM' and
719(depending on the OS) 15 are all valid arguments to C<-E<gt>kill()>.
720
721Returns the thread object to allow for method chaining:
722
723 $thr->kill('SIG...')->join();
724
725=back
726
727Signal handlers need to be set up in the threads for the signals they are
728expected to act upon. Here's an example for I<cancelling> a thread:
729
730 use threads;
731
c0003851
JH
732 sub thr_func
733 {
734 # Thread 'cancellation' signal handler
c608f8c0 735 $SIG{'KILL'} = sub { threads->exit(); };
c0003851
JH
736
737 ...
738 }
739
740 # Create a thread
741 my $thr = threads->create('thr_func');
742
743 ...
744
745 # Signal the thread to terminate, and then detach
746 # it so that it will get cleaned up automatically
747 $thr->kill('KILL')->detach();
748
404aaa48
JH
749Here's another simplistic example that illustrates the use of thread
750signalling in conjunction with a semaphore to provide rudimentary I<suspend>
751and I<resume> capabilities:
c0003851
JH
752
753 use threads;
754 use Thread::Semaphore;
755
756 sub thr_func
757 {
758 my $sema = shift;
759
760 # Thread 'suspend/resume' signal handler
761 $SIG{'STOP'} = sub {
762 $sema->down(); # Thread suspended
763 $sema->up(); # Thread resumes
764 };
765
766 ...
767 }
768
5cbb7319 769 # Create a semaphore and pass it to a thread
c0003851
JH
770 my $sema = Thread::Semaphore->new();
771 my $thr = threads->create('thr_func', $sema);
772
773 # Suspend the thread
774 $sema->down();
775 $thr->kill('STOP');
776
777 ...
778
779 # Allow the thread to continue
780 $sema->up();
781
404aaa48
JH
782CAVEAT: The thread signalling capability provided by this module does not
783actually send signals via the OS. It I<emulates> signals at the Perl-level
784such that signal handlers are called in the appropriate thread. For example,
785sending C<$thr-E<gt>kill('STOP')> does not actually suspend a thread (or the
786whole process), but does cause a C<$SIG{'STOP'}> handler to be called in that
787thread (as illustrated above).
788
789As such, signals that would normally not be appropriate to use in the
790C<kill()> command (e.g., C<kill('KILL', $$)>) are okay to use with the
791C<-E<gt>kill()> method (again, as illustrated above).
792
793Correspondingly, sending a signal to a thread does not disrupt the operation
794the thread is currently working on: The signal will be acted upon after the
c0003851
JH
795current operation has completed. For instance, if the thread is I<stuck> on
796an I/O call, sending it a signal will not cause the I/O call to be interrupted
797such that the signal is acted up immediately.
798
99f57afc 799Sending a signal to a terminated/finished thread is ignored.
69a9b4b8 800
e4f9f4fe
JH
801=head1 WARNINGS
802
803=over 4
804
4dcb9e53 805=item Perl exited with active threads:
e4f9f4fe 806
4dcb9e53
JH
807If the program exits without all threads having either been joined or
808detached, then this warning will be issued.
809
69a9b4b8
RGS
810NOTE: If the I<main> thread exits, then this warning cannot be suppressed
811using C<no warnings 'threads';> as suggested below.
e4f9f4fe 812
c0003851
JH
813=item Thread creation failed: pthread_create returned #
814
815See the appropriate I<man> page for C<pthread_create> to determine the actual
816cause for the failure.
817
818=item Thread # terminated abnormally: ...
819
820A thread terminated in some manner other than just returning from its entry
955c272e 821point function, or by using C<threads-E<gt>exit()>. For example, the thread
5cbb7319 822may have terminated because of an error, or by using C<die>.
c0003851 823
514612b7
JH
824=item Using minimum thread stack size of #
825
826Some platforms have a minimum thread stack size. Trying to set the stack size
827below this value will result in the above warning, and the stack size will be
828set to the minimum.
829
c0003851
JH
830=item Thread creation failed: pthread_attr_setstacksize(I<SIZE>) returned 22
831
832The specified I<SIZE> exceeds the system's maximum stack size. Use a smaller
833value for the stack size.
834
e4f9f4fe 835=back
47ba8780 836
c0003851
JH
837If needed, thread warnings can be suppressed by using:
838
839 no warnings 'threads';
840
841in the appropriate scope.
842
0f1612a7
JH
843=head1 ERRORS
844
845=over 4
846
fcea4b7c 847=item This Perl not built to support threads
678a9b6c 848
0f1612a7
JH
849The particular copy of Perl that you're trying to use was not built using the
850C<useithreads> configuration option.
678a9b6c 851
0f1612a7
JH
852Having threads support requires all of Perl and all of the XS modules in the
853Perl installation to be rebuilt; it is not just a question of adding the
854L<threads> module (i.e., threaded and non-threaded Perls are binary
99f57afc 855incompatible).
0f1612a7 856
514612b7
JH
857=item Cannot change stack size of an existing thread
858
859The stack size of currently extant threads cannot be changed, therefore, the
860following results in the above error:
861
862 $thr->set_stack_size($size);
863
4dcb9e53 864=item Cannot signal threads without safe signals
514612b7 865
1152d448 866Safe signals must be in effect to use the C<-E<gt>kill()> signalling method.
9d9ff5b1 867See L</"Unsafe signals"> for more details.
c0003851
JH
868
869=item Unrecognized signal name: ...
870
871The particular copy of Perl that you're trying to use does not support the
872specified signal being used in a C<-E<gt>kill()> call.
514612b7 873
0f1612a7 874=back
47ba8780 875
b9c1db01
JH
876=head1 BUGS AND LIMITATIONS
877
878Before you consider posting a bug report, please consult, and possibly post a
879message to the discussion forum to see if what you've encountered is a known
880problem.
5c6ff896
JH
881
882=over
883
938aad41 884=item Thread-safe modules
c527c90b
JH
885
886See L<perlmod/"Making your module threadsafe"> when creating modules that may
887be used in threaded applications, especially if those modules use non-Perl
888data, or XS code.
889
938aad41 890=item Using non-thread-safe modules
5c6ff896 891
938aad41
JH
892Unfortunately, you may encounter Perl modules that are not I<thread-safe>.
893For example, they may crash the Perl interpreter during execution, or may dump
5c6ff896
JH
894core on termination. Depending on the module and the requirements of your
895application, it may be possible to work around such difficulties.
896
897If the module will only be used inside a thread, you can try loading the
898module from inside the thread entry point function using C<require> (and
899C<import> if needed):
900
901 sub thr_func
902 {
903 require Unsafe::Module
f3086ff0 904 # Unsafe::Module->import(...);
5c6ff896
JH
905
906 ....
907 }
908
955c272e
JH
909If the module is needed inside the I<main> thread, try modifying your
910application so that the module is loaded (again using C<require> and
f3086ff0
JH
911C<-E<gt>import()>) after any threads are started, and in such a way that no
912other threads are started afterwards.
5c6ff896
JH
913
914If the above does not work, or is not adequate for your application, then file
915a bug report on L<http://rt.cpan.org/Public/> against the problematic module.
916
b91a79b9
SM
917=item Memory consumption
918
919On most systems, frequent and continual creation and destruction of threads
920can lead to ever-increasing growth in the memory footprint of the Perl
921interpreter. While it is simple to just launch threads and then
922C<-E<gt>join()> or C<-E<gt>detach()> them, for long-lived applications, it is
923better to maintain a pool of threads, and to reuse them for the work needed,
924using L<queues|Thread::Queue> to notify threads of pending work. The CPAN
925distribution of this module contains a simple example
926(F<examples/pool_reuse.pl>) illustrating the creation, use and monitoring of a
927pool of I<reusable> threads.
928
f3086ff0
JH
929=item Current working directory
930
931On all platforms except MSWin32, the setting for the current working directory
932is shared among all threads such that changing it in one thread (e.g., using
933C<chdir()>) will affect all the threads in the application.
934
935On MSWin32, each thread maintains its own the current working directory
936setting.
937
938=item Environment variables
939
940Currently, on all platforms except MSWin32, all I<system> calls (e.g., using
941C<system()> or back-ticks) made from threads use the environment variable
942settings from the I<main> thread. In other words, changes made to C<%ENV> in
943a thread will not be visible in I<system> calls made by that thread.
944
945To work around this, set environment variables as part of the I<system> call.
946For example:
947
948 my $msg = 'hello';
949 system("FOO=$msg; echo \$FOO"); # Outputs 'hello' to STDOUT
950
951On MSWin32, each thread maintains its own set of environment variables.
952
794373aa
JH
953=item Catching signals
954
955Signals are I<caught> by the main thread (thread ID = 0) of a script.
956Therefore, setting up signal handlers in threads for purposes other than
957L</"THREAD SIGNALLING"> as documented above will not accomplish what is
958intended.
959
960This is especially true if trying to catch C<SIGALRM> in a thread. To handle
961alarms in threads, set up a signal handler in the main thread, and then use
962L</"THREAD SIGNALLING"> to relay the signal to the thread:
963
964 # Create thread with a task that may time out
afb37b32 965 my $thr = threads->create(sub {
794373aa
JH
966 threads->yield();
967 eval {
968 $SIG{ALRM} = sub { die("Timeout\n"); };
969 alarm(10);
970 ... # Do work here
971 alarm(0);
972 };
973 if ($@ =~ /Timeout/) {
974 warn("Task in thread timed out\n");
975 }
976 };
977
978 # Set signal handler to relay SIGALRM to thread
979 $SIG{ALRM} = sub { $thr->kill('ALRM') };
980
981 ... # Main thread continues working
982
fcea4b7c 983=item Parent-child threads
678a9b6c 984
fcea4b7c
JH
985On some platforms, it might not be possible to destroy I<parent> threads while
986there are still existing I<child> threads.
678a9b6c 987
404aaa48 988=item Creating threads inside special blocks
88f8c1df 989
f2e0bb91
JH
990Creating threads inside C<BEGIN>, C<CHECK> or C<INIT> blocks should not be
991relied upon. Depending on the Perl version and the application code, results
58a3a76c 992may range from success, to (apparently harmless) warnings of leaked scalar, or
f2e0bb91 993all the way up to crashing of the Perl interpreter.
88f8c1df 994
1152d448 995=item Unsafe signals
47ba8780 996
1152d448
JH
997Since Perl 5.8.0, signals have been made safer in Perl by postponing their
998handling until the interpreter is in a I<safe> state. See
404aaa48 999L<perl58delta/"Safe Signals"> and L<perlipc/"Deferred Signals (Safe Signals)">
1152d448
JH
1000for more details.
1001
1002Safe signals is the default behavior, and the old, immediate, unsafe
1003signalling behavior is only in effect in the following situations:
1004
1005=over 4
1006
5cbb7319 1007=item * Perl has been built with C<PERL_OLD_SIGNALS> (see C<perl -V>).
1152d448 1008
9eb07988 1009=item * The environment variable C<PERL_SIGNALS> is set to C<unsafe>
1010(see L<perlrun/"PERL_SIGNALS">).
1152d448
JH
1011
1012=item * The module L<Perl::Unsafe::Signals> is used.
1013
1014=back
1015
1016If unsafe signals is in effect, then signal handling is not thread-safe, and
1017the C<-E<gt>kill()> signalling method cannot be used.
88f8c1df 1018
0f1612a7
JH
1019=item Returning closures from threads
1020
99f57afc 1021Returning closures from threads should not be relied upon. Depending on the
f2e0bb91 1022Perl version and the application code, results may range from success, to
58a3a76c
JH
1023(apparently harmless) warnings of leaked scalar, or all the way up to crashing
1024of the Perl interpreter.
0f1612a7 1025
955c272e
JH
1026=item Returning objects from threads
1027
b9c1db01
JH
1028Returning objects from threads does not work. Depending on the classes
1029involved, you may be able to work around this by returning a serialized
1030version of the object (e.g., using L<Data::Dumper> or L<Storable>), and then
7ef93cb2
JH
1031reconstituting it in the joining thread. If you're using Perl 5.10.0 or
1032later, and if the class supports L<shared objects|threads::shared/"OBJECTS">,
b91a79b9 1033you can pass them via L<shared queues|Thread::Queue>.
955c272e 1034
561ee912
JH
1035=item END blocks in threads
1036
1037It is possible to add L<END blocks|perlmod/"BEGIN, UNITCHECK, CHECK, INIT and
1038END"> to threads by using L<require|perlfunc/"require VERSION"> or
1039L<eval|perlfunc/"eval EXPR"> with the appropriate code. These C<END> blocks
1040will then be executed when the thread's interpreter is destroyed (i.e., either
1041during a C<-E<gt>join()> call, or at program termination).
1042
1043However, calling any L<threads> methods in such an C<END> block will most
1044likely I<fail> (e.g., the application may hang, or generate an error) due to
1045mutexes that are needed to control functionality within the L<threads> module.
1046
1047For this reason, the use of C<END> blocks in threads is B<strongly>
1048discouraged.
1049
414fa04c
JH
1050=item Open directory handles
1051
c2053ddb
FC
1052In perl 5.14 and higher, on systems other than Windows that do
1053not support the C<fchdir> C function, directory handles (see
89cf1afa
FC
1054L<opendir|perlfunc/"opendir DIRHANDLE,EXPR">) will not be copied to new
1055threads. You can use the C<d_fchdir> variable in L<Config.pm|Config> to
1056determine whether your system supports it.
1057
1058In prior perl versions, spawning threads with open directory handles would
1059crash the interpreter.
414fa04c
JH
1060L<[perl #75154]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=75154>
1061
0f1612a7
JH
1062=item Perl Bugs and the CPAN Version of L<threads>
1063
5cbb7319 1064Support for threads extends beyond the code in this module (i.e.,
938aad41 1065F<threads.pm> and F<threads.xs>), and into the Perl interpreter itself. Older
0f1612a7
JH
1066versions of Perl contain bugs that may manifest themselves despite using the
1067latest version of L<threads> from CPAN. There is no workaround for this other
938aad41 1068than upgrading to the latest version of Perl.
0f1612a7 1069
938aad41 1070Even with the latest version of Perl, it is known that certain constructs
c527c90b
JH
1071with threads may result in warning messages concerning leaked scalars or
1072unreferenced scalars. However, such warnings are harmless, and may safely be
1073ignored.
1074
7ef93cb2
JH
1075You can search for L<threads> related bug reports at
1076L<http://rt.cpan.org/Public/>. If needed submit any new bugs, problems,
1077patches, etc. to: L<http://rt.cpan.org/Public/Dist/Display.html?Name=threads>
1078
47ba8780
AB
1079=back
1080
0f1612a7 1081=head1 REQUIREMENTS
47ba8780 1082
0f1612a7 1083Perl 5.8.0 or later
47ba8780 1084
0f1612a7 1085=head1 SEE ALSO
47ba8780 1086
0f1612a7
JH
1087L<threads> Discussion Forum on CPAN:
1088L<http://www.cpanforum.com/dist/threads>
47ba8780 1089
0f1612a7 1090L<threads::shared>, L<perlthrtut>
47ba8780 1091
0f1612a7
JH
1092L<http://www.perl.com/pub/a/2002/06/11/threads.html> and
1093L<http://www.perl.com/pub/a/2002/09/04/threads.html>
47ba8780 1094
0f1612a7 1095Perl threads mailing list:
d185f61f 1096L<http://lists.perl.org/list/ithreads.html>
47ba8780 1097
514612b7
JH
1098Stack size discussion:
1099L<http://www.perlmonks.org/?node_id=532956>
1100
0f1612a7 1101=head1 AUTHOR
47ba8780 1102
0f1612a7
JH
1103Artur Bergman E<lt>sky AT crucially DOT netE<gt>
1104
0f1612a7
JH
1105CPAN version produced by Jerry D. Hedden <jdhedden AT cpan DOT org>
1106
561ee912
JH
1107=head1 LICENSE
1108
1109threads is released under the same license as Perl.
1110
0f1612a7
JH
1111=head1 ACKNOWLEDGEMENTS
1112
1113Richard Soderberg E<lt>perl AT crystalflame DOT netE<gt> -
1114Helping me out tons, trying to find reasons for races and other weird bugs!
1115
1116Simon Cozens E<lt>simon AT brecon DOT co DOT ukE<gt> -
1117Being there to answer zillions of annoying questions
1118
1119Rocco Caputo E<lt>troc AT netrus DOT netE<gt>
47ba8780 1120
0f1612a7
JH
1121Vipul Ved Prakash E<lt>mail AT vipul DOT netE<gt> -
1122Helping with debugging
47ba8780 1123
514612b7
JH
1124Dean Arnold E<lt>darnold AT presicient DOT comE<gt> -
1125Stack size API
1126
47ba8780 1127=cut