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