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