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