This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Add thread-safe locale handling
[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
e9bc6d6b 8our $VERSION = '2.22'; # remember to update version in POD!
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
7347ee54 137This document describes threads version 2.21
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
d9262b38 366 use threads qw(stringify);
3ab14376 367
d9262b38 368 my $thr = threads->create(...);
369 print("Thread $thr started\n"); # Prints: 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 693
d9262b38 694 my $thr = threads->create({'stack_size' => 32*4096},
695 \&foo, @args);
514612b7
JH
696
697=item $thr2 = $thr1->create(FUNCTION, ARGS)
698
699This creates a new thread (C<$thr2>) that inherits the stack size from an
700existing thread (C<$thr1>). This is shorthand for the following:
701
d9262b38 702 my $stack_size = $thr1->get_stack_size();
703 my $thr2 = threads->create({'stack_size' => $stack_size},
704 FUNCTION, ARGS);
514612b7
JH
705
706=back
707
c0003851
JH
708=head1 THREAD SIGNALLING
709
9d9ff5b1 710When safe signals is in effect (the default behavior - see L</"Unsafe signals">
1152d448
JH
711for more details), then signals may be sent and acted upon by individual
712threads.
c0003851
JH
713
714=over 4
715
716=item $thr->kill('SIG...');
717
718Sends the specified signal to the thread. Signal names and (positive) signal
719numbers are the same as those supported by
720L<kill()|perlfunc/"kill SIGNAL, LIST">. For example, 'SIGTERM', 'TERM' and
721(depending on the OS) 15 are all valid arguments to C<-E<gt>kill()>.
722
723Returns the thread object to allow for method chaining:
724
725 $thr->kill('SIG...')->join();
726
727=back
728
729Signal handlers need to be set up in the threads for the signals they are
730expected to act upon. Here's an example for I<cancelling> a thread:
731
732 use threads;
733
c0003851
JH
734 sub thr_func
735 {
736 # Thread 'cancellation' signal handler
c608f8c0 737 $SIG{'KILL'} = sub { threads->exit(); };
c0003851
JH
738
739 ...
740 }
741
742 # Create a thread
743 my $thr = threads->create('thr_func');
744
745 ...
746
747 # Signal the thread to terminate, and then detach
748 # it so that it will get cleaned up automatically
749 $thr->kill('KILL')->detach();
750
404aaa48
JH
751Here's another simplistic example that illustrates the use of thread
752signalling in conjunction with a semaphore to provide rudimentary I<suspend>
753and I<resume> capabilities:
c0003851
JH
754
755 use threads;
756 use Thread::Semaphore;
757
758 sub thr_func
759 {
760 my $sema = shift;
761
762 # Thread 'suspend/resume' signal handler
763 $SIG{'STOP'} = sub {
764 $sema->down(); # Thread suspended
765 $sema->up(); # Thread resumes
766 };
767
768 ...
769 }
770
5cbb7319 771 # Create a semaphore and pass it to a thread
c0003851
JH
772 my $sema = Thread::Semaphore->new();
773 my $thr = threads->create('thr_func', $sema);
774
775 # Suspend the thread
776 $sema->down();
777 $thr->kill('STOP');
778
779 ...
780
781 # Allow the thread to continue
782 $sema->up();
783
404aaa48
JH
784CAVEAT: The thread signalling capability provided by this module does not
785actually send signals via the OS. It I<emulates> signals at the Perl-level
786such that signal handlers are called in the appropriate thread. For example,
787sending C<$thr-E<gt>kill('STOP')> does not actually suspend a thread (or the
788whole process), but does cause a C<$SIG{'STOP'}> handler to be called in that
789thread (as illustrated above).
790
791As such, signals that would normally not be appropriate to use in the
792C<kill()> command (e.g., C<kill('KILL', $$)>) are okay to use with the
793C<-E<gt>kill()> method (again, as illustrated above).
794
795Correspondingly, sending a signal to a thread does not disrupt the operation
796the thread is currently working on: The signal will be acted upon after the
c0003851
JH
797current operation has completed. For instance, if the thread is I<stuck> on
798an I/O call, sending it a signal will not cause the I/O call to be interrupted
799such that the signal is acted up immediately.
800
99f57afc 801Sending a signal to a terminated/finished thread is ignored.
69a9b4b8 802
e4f9f4fe
JH
803=head1 WARNINGS
804
805=over 4
806
4dcb9e53 807=item Perl exited with active threads:
e4f9f4fe 808
4dcb9e53
JH
809If the program exits without all threads having either been joined or
810detached, then this warning will be issued.
811
69a9b4b8
RGS
812NOTE: If the I<main> thread exits, then this warning cannot be suppressed
813using C<no warnings 'threads';> as suggested below.
e4f9f4fe 814
c0003851
JH
815=item Thread creation failed: pthread_create returned #
816
817See the appropriate I<man> page for C<pthread_create> to determine the actual
818cause for the failure.
819
820=item Thread # terminated abnormally: ...
821
822A thread terminated in some manner other than just returning from its entry
955c272e 823point function, or by using C<threads-E<gt>exit()>. For example, the thread
5cbb7319 824may have terminated because of an error, or by using C<die>.
c0003851 825
514612b7
JH
826=item Using minimum thread stack size of #
827
828Some platforms have a minimum thread stack size. Trying to set the stack size
829below this value will result in the above warning, and the stack size will be
830set to the minimum.
831
c0003851
JH
832=item Thread creation failed: pthread_attr_setstacksize(I<SIZE>) returned 22
833
834The specified I<SIZE> exceeds the system's maximum stack size. Use a smaller
835value for the stack size.
836
e4f9f4fe 837=back
47ba8780 838
c0003851
JH
839If needed, thread warnings can be suppressed by using:
840
841 no warnings 'threads';
842
843in the appropriate scope.
844
0f1612a7
JH
845=head1 ERRORS
846
847=over 4
848
fcea4b7c 849=item This Perl not built to support threads
678a9b6c 850
0f1612a7
JH
851The particular copy of Perl that you're trying to use was not built using the
852C<useithreads> configuration option.
678a9b6c 853
0f1612a7
JH
854Having threads support requires all of Perl and all of the XS modules in the
855Perl installation to be rebuilt; it is not just a question of adding the
856L<threads> module (i.e., threaded and non-threaded Perls are binary
99f57afc 857incompatible).
0f1612a7 858
514612b7
JH
859=item Cannot change stack size of an existing thread
860
861The stack size of currently extant threads cannot be changed, therefore, the
862following results in the above error:
863
864 $thr->set_stack_size($size);
865
4dcb9e53 866=item Cannot signal threads without safe signals
514612b7 867
1152d448 868Safe signals must be in effect to use the C<-E<gt>kill()> signalling method.
9d9ff5b1 869See L</"Unsafe signals"> for more details.
c0003851
JH
870
871=item Unrecognized signal name: ...
872
873The particular copy of Perl that you're trying to use does not support the
874specified signal being used in a C<-E<gt>kill()> call.
514612b7 875
0f1612a7 876=back
47ba8780 877
b9c1db01
JH
878=head1 BUGS AND LIMITATIONS
879
880Before you consider posting a bug report, please consult, and possibly post a
881message to the discussion forum to see if what you've encountered is a known
882problem.
5c6ff896
JH
883
884=over
885
938aad41 886=item Thread-safe modules
c527c90b
JH
887
888See L<perlmod/"Making your module threadsafe"> when creating modules that may
889be used in threaded applications, especially if those modules use non-Perl
890data, or XS code.
891
938aad41 892=item Using non-thread-safe modules
5c6ff896 893
938aad41
JH
894Unfortunately, you may encounter Perl modules that are not I<thread-safe>.
895For example, they may crash the Perl interpreter during execution, or may dump
5c6ff896
JH
896core on termination. Depending on the module and the requirements of your
897application, it may be possible to work around such difficulties.
898
899If the module will only be used inside a thread, you can try loading the
900module from inside the thread entry point function using C<require> (and
901C<import> if needed):
902
903 sub thr_func
904 {
905 require Unsafe::Module
f3086ff0 906 # Unsafe::Module->import(...);
5c6ff896
JH
907
908 ....
909 }
910
955c272e
JH
911If the module is needed inside the I<main> thread, try modifying your
912application so that the module is loaded (again using C<require> and
f3086ff0
JH
913C<-E<gt>import()>) after any threads are started, and in such a way that no
914other threads are started afterwards.
5c6ff896
JH
915
916If the above does not work, or is not adequate for your application, then file
917a bug report on L<http://rt.cpan.org/Public/> against the problematic module.
918
b91a79b9
SM
919=item Memory consumption
920
921On most systems, frequent and continual creation and destruction of threads
922can lead to ever-increasing growth in the memory footprint of the Perl
923interpreter. While it is simple to just launch threads and then
924C<-E<gt>join()> or C<-E<gt>detach()> them, for long-lived applications, it is
925better to maintain a pool of threads, and to reuse them for the work needed,
926using L<queues|Thread::Queue> to notify threads of pending work. The CPAN
927distribution of this module contains a simple example
928(F<examples/pool_reuse.pl>) illustrating the creation, use and monitoring of a
929pool of I<reusable> threads.
930
f3086ff0
JH
931=item Current working directory
932
933On all platforms except MSWin32, the setting for the current working directory
934is shared among all threads such that changing it in one thread (e.g., using
935C<chdir()>) will affect all the threads in the application.
936
937On MSWin32, each thread maintains its own the current working directory
938setting.
939
e9bc6d6b
KW
940=item Locales
941
942Prior to Perl 5.28, locales could not be used with threads, due to various
943race conditions. Starting in that release, on systems that implement
944thread-safe locale functions, threads can be used, with some caveats.
945This includes Windows starting with Visual Studio 2005, and systems compatible
946with POSIX 2008. See L<perllocale/Multi-threaded operation>.
947
948Each thread (except the main thread) is started using the C locale. The main
949thread is started like all other Perl programs; see L<perllocale/ENVIRONMENT>.
950You can switch locales in any thread as often as you like.
951
952If you want to inherit the parent thread's locale, you can, in the parent, set
953a variable like so:
954
955 $foo = POSIX::setlocale(LC_ALL, NULL);
956
957and then pass to threads->create() a sub that closes over C<$foo>. Then, in
958the child, you say
959
960 POSIX::setlocale(LC_ALL, $foo);
961
962Or you can use the facilities in L<threads::shared> to pass C<$foo>;
963or if the environment hasn't changed, in the child, do
964
965 POSIX::setlocale(LC_ALL, "");
966
f3086ff0
JH
967=item Environment variables
968
969Currently, on all platforms except MSWin32, all I<system> calls (e.g., using
970C<system()> or back-ticks) made from threads use the environment variable
971settings from the I<main> thread. In other words, changes made to C<%ENV> in
972a thread will not be visible in I<system> calls made by that thread.
973
974To work around this, set environment variables as part of the I<system> call.
975For example:
976
977 my $msg = 'hello';
978 system("FOO=$msg; echo \$FOO"); # Outputs 'hello' to STDOUT
979
980On MSWin32, each thread maintains its own set of environment variables.
981
794373aa
JH
982=item Catching signals
983
984Signals are I<caught> by the main thread (thread ID = 0) of a script.
985Therefore, setting up signal handlers in threads for purposes other than
986L</"THREAD SIGNALLING"> as documented above will not accomplish what is
987intended.
988
989This is especially true if trying to catch C<SIGALRM> in a thread. To handle
990alarms in threads, set up a signal handler in the main thread, and then use
991L</"THREAD SIGNALLING"> to relay the signal to the thread:
992
993 # Create thread with a task that may time out
afb37b32 994 my $thr = threads->create(sub {
794373aa
JH
995 threads->yield();
996 eval {
997 $SIG{ALRM} = sub { die("Timeout\n"); };
998 alarm(10);
999 ... # Do work here
1000 alarm(0);
1001 };
1002 if ($@ =~ /Timeout/) {
1003 warn("Task in thread timed out\n");
1004 }
1005 };
1006
1007 # Set signal handler to relay SIGALRM to thread
1008 $SIG{ALRM} = sub { $thr->kill('ALRM') };
1009
1010 ... # Main thread continues working
1011
fcea4b7c 1012=item Parent-child threads
678a9b6c 1013
fcea4b7c
JH
1014On some platforms, it might not be possible to destroy I<parent> threads while
1015there are still existing I<child> threads.
678a9b6c 1016
1152d448 1017=item Unsafe signals
47ba8780 1018
1152d448
JH
1019Since Perl 5.8.0, signals have been made safer in Perl by postponing their
1020handling until the interpreter is in a I<safe> state. See
404aaa48 1021L<perl58delta/"Safe Signals"> and L<perlipc/"Deferred Signals (Safe Signals)">
1152d448
JH
1022for more details.
1023
1024Safe signals is the default behavior, and the old, immediate, unsafe
1025signalling behavior is only in effect in the following situations:
1026
1027=over 4
1028
5cbb7319 1029=item * Perl has been built with C<PERL_OLD_SIGNALS> (see C<perl -V>).
1152d448 1030
9eb07988 1031=item * The environment variable C<PERL_SIGNALS> is set to C<unsafe>
1032(see L<perlrun/"PERL_SIGNALS">).
1152d448
JH
1033
1034=item * The module L<Perl::Unsafe::Signals> is used.
1035
1036=back
1037
1038If unsafe signals is in effect, then signal handling is not thread-safe, and
1039the C<-E<gt>kill()> signalling method cannot be used.
88f8c1df 1040
27d3197f
Z
1041=item Identity of objects returned from threads
1042
1043When a value is returned from a thread through a C<join> operation,
1044the value and everything that it references is copied across to the
1045joining thread, in much the same way that values are copied upon thread
1046creation. This works fine for most kinds of value, including arrays,
1047hashes, and subroutines. The copying recurses through array elements,
1048reference scalars, variables closed over by subroutines, and other kinds
1049of reference.
0f1612a7 1050
27d3197f
Z
1051However, everything referenced by the returned value is a fresh copy in
1052the joining thread, even if a returned object had in the child thread
1053been a copy of something that previously existed in the parent thread.
1054After joining, the parent will therefore have a duplicate of each such
1055object. This sometimes matters, especially if the object gets mutated;
1056this can especially matter for private data to which a returned subroutine
1057provides access.
0f1612a7 1058
27d3197f 1059=item Returning blessed objects from threads
955c272e 1060
27d3197f 1061Returning blessed objects from threads does not work. Depending on the classes
b9c1db01
JH
1062involved, you may be able to work around this by returning a serialized
1063version of the object (e.g., using L<Data::Dumper> or L<Storable>), and then
7ef93cb2
JH
1064reconstituting it in the joining thread. If you're using Perl 5.10.0 or
1065later, and if the class supports L<shared objects|threads::shared/"OBJECTS">,
b91a79b9 1066you can pass them via L<shared queues|Thread::Queue>.
955c272e 1067
561ee912
JH
1068=item END blocks in threads
1069
1070It is possible to add L<END blocks|perlmod/"BEGIN, UNITCHECK, CHECK, INIT and
1071END"> to threads by using L<require|perlfunc/"require VERSION"> or
1072L<eval|perlfunc/"eval EXPR"> with the appropriate code. These C<END> blocks
1073will then be executed when the thread's interpreter is destroyed (i.e., either
1074during a C<-E<gt>join()> call, or at program termination).
1075
1076However, calling any L<threads> methods in such an C<END> block will most
1077likely I<fail> (e.g., the application may hang, or generate an error) due to
1078mutexes that are needed to control functionality within the L<threads> module.
1079
1080For this reason, the use of C<END> blocks in threads is B<strongly>
1081discouraged.
1082
414fa04c
JH
1083=item Open directory handles
1084
c2053ddb
FC
1085In perl 5.14 and higher, on systems other than Windows that do
1086not support the C<fchdir> C function, directory handles (see
89cf1afa
FC
1087L<opendir|perlfunc/"opendir DIRHANDLE,EXPR">) will not be copied to new
1088threads. You can use the C<d_fchdir> variable in L<Config.pm|Config> to
1089determine whether your system supports it.
1090
1091In prior perl versions, spawning threads with open directory handles would
1092crash the interpreter.
414fa04c
JH
1093L<[perl #75154]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=75154>
1094
5ea3460b 1095=item Detached threads and global destruction
1096
1097If the main thread exits while there are detached threads which are still
1098running, then Perl's global destruction phase is not executed because
1099otherwise certain global structures that control the operation of threads and
1100that are allocated in the main thread's memory may get destroyed before the
1101detached thread is destroyed.
1102
1103If you are using any code that requires the execution of the global
1104destruction phase for clean up (e.g., removing temp files), then do not use
1105detached threads, but rather join all threads before exiting the program.
1106
0f1612a7
JH
1107=item Perl Bugs and the CPAN Version of L<threads>
1108
5cbb7319 1109Support for threads extends beyond the code in this module (i.e.,
938aad41 1110F<threads.pm> and F<threads.xs>), and into the Perl interpreter itself. Older
0f1612a7
JH
1111versions of Perl contain bugs that may manifest themselves despite using the
1112latest version of L<threads> from CPAN. There is no workaround for this other
938aad41 1113than upgrading to the latest version of Perl.
0f1612a7 1114
938aad41 1115Even with the latest version of Perl, it is known that certain constructs
c527c90b
JH
1116with threads may result in warning messages concerning leaked scalars or
1117unreferenced scalars. However, such warnings are harmless, and may safely be
1118ignored.
1119
7ef93cb2
JH
1120You can search for L<threads> related bug reports at
1121L<http://rt.cpan.org/Public/>. If needed submit any new bugs, problems,
1122patches, etc. to: L<http://rt.cpan.org/Public/Dist/Display.html?Name=threads>
1123
47ba8780
AB
1124=back
1125
0f1612a7 1126=head1 REQUIREMENTS
47ba8780 1127
0f1612a7 1128Perl 5.8.0 or later
47ba8780 1129
0f1612a7 1130=head1 SEE ALSO
47ba8780 1131
95ec88f9 1132threads on MetaCPAN:
1133L<https://metacpan.org/release/threads>
1134
1135Code repository for CPAN distribution:
1136L<https://github.com/Dual-Life/threads>
47ba8780 1137
0f1612a7 1138L<threads::shared>, L<perlthrtut>
47ba8780 1139
0f1612a7
JH
1140L<http://www.perl.com/pub/a/2002/06/11/threads.html> and
1141L<http://www.perl.com/pub/a/2002/09/04/threads.html>
47ba8780 1142
0f1612a7 1143Perl threads mailing list:
d185f61f 1144L<http://lists.perl.org/list/ithreads.html>
47ba8780 1145
514612b7
JH
1146Stack size discussion:
1147L<http://www.perlmonks.org/?node_id=532956>
1148
95ec88f9 1149Sample code in the I<examples> directory of this distribution on CPAN.
1150
0f1612a7 1151=head1 AUTHOR
47ba8780 1152
0f1612a7
JH
1153Artur Bergman E<lt>sky AT crucially DOT netE<gt>
1154
0f1612a7
JH
1155CPAN version produced by Jerry D. Hedden <jdhedden AT cpan DOT org>
1156
561ee912
JH
1157=head1 LICENSE
1158
1159threads is released under the same license as Perl.
1160
0f1612a7
JH
1161=head1 ACKNOWLEDGEMENTS
1162
1163Richard Soderberg E<lt>perl AT crystalflame DOT netE<gt> -
1164Helping me out tons, trying to find reasons for races and other weird bugs!
1165
1166Simon Cozens E<lt>simon AT brecon DOT co DOT ukE<gt> -
1167Being there to answer zillions of annoying questions
1168
1169Rocco Caputo E<lt>troc AT netrus DOT netE<gt>
47ba8780 1170
0f1612a7
JH
1171Vipul Ved Prakash E<lt>mail AT vipul DOT netE<gt> -
1172Helping with debugging
47ba8780 1173
514612b7
JH
1174Dean Arnold E<lt>darnold AT presicient DOT comE<gt> -
1175Stack size API
1176
47ba8780 1177=cut