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