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