9 my $XS_VERSION = $VERSION;
10 $VERSION = eval $VERSION;
14 # Verify this Perl supports threads
16 if (! $Config{useithreads}) {
17 die("This Perl not built to support threads\n");
20 # Declare that we have been loaded
21 $threads::threads = 1;
23 # Complain if 'threads' is loaded after 'threads::shared'
24 if ($threads::shared::threads_shared) {
26 Warning, threads::shared has already been loaded. To
27 enable shared variables, 'use threads' must be called
28 before threads::shared or any module that uses it.
36 XSLoader::load('threads', $XS_VERSION);
43 my $class = shift; # Not used
45 # Exported subroutines
46 my @EXPORT = qw(async);
49 while (my $sym = shift) {
50 if ($sym =~ /^stack/) {
51 threads->set_stack_size(shift);
53 } elsif ($sym =~ /all/) {
54 push(@EXPORT, qw(yield));
61 # Export subroutine names
62 my $caller = caller();
63 foreach my $sym (@EXPORT) {
65 *{$caller.'::'.$sym} = \&{$sym};
68 # Set stack size via environment variable
69 if (exists($ENV{'PERL5_ITHREADS_STACK_SIZE'})) {
70 threads->set_stack_size($ENV{'PERL5_ITHREADS_STACK_SIZE'});
77 # Our own exit function/method
83 # 'Constant' args for threads->list()
85 sub threads::running { 1 }
86 sub threads::joinable { 0 }
88 # 'new' is an alias for 'create'
91 # 'async' is a function alias for the 'threads->create()' method
94 unshift(@_, 'threads');
95 # Use "goto" trick to avoid pad problems from 5.8.1 (fixed in 5.8.2)
99 # Thread object equality checking
102 '!=' => sub { ! equal(@_) },
112 threads - Perl interpreter-based threads
116 This document describes threads version 1.36
120 use threads ('yield', 'stack_size' => 64*4096);
124 print('Thread started: ', join(' ', @args), "\n");
126 my $thread = threads->create('start_thread', 'argument');
129 threads->create(sub { print("I am a thread\n"); })->join();
131 my $thread3 = async { foreach (@files) { ... } };
134 # Invoke thread in list context (implicit) so it can return a list
135 my ($thr) = threads->create(sub { return (qw/a b c/); });
136 # or specify list context explicitly
137 my $thr = threads->create({'context' => 'list'},
138 sub { return (qw/a b c/); });
139 my @results = $thr->join();
143 $thread = threads->self();
144 $thread = threads->object($tid);
146 $tid = threads->tid();
147 $tid = threads->self->tid();
148 $tid = $thread->tid();
153 my @threads = threads->list();
154 my $thread_count = threads->list();
156 my @running = threads->list(threads::running);
157 my @joinable = threads->list(threads::joinable);
159 if ($thr1 == $thr2) {
163 $stack_size = threads->get_stack_size();
164 $old_size = threads->set_stack_size(32*4096);
166 # Create a thread with a specific context and stack size
167 my $thr = threads->create({ 'context' => 'list',
168 'stack_size' => 32*4096 },
171 # Get thread's context
172 my $wantarray = $thr->wantarray();
174 # Check thread's state
175 if ($thr->is_running()) {
178 if ($thr->is_joinable()) {
182 $thr->kill('SIGUSR1');
188 Perl 5.6 introduced something called interpreter threads. Interpreter threads
189 are different from I<5005threads> (the thread model of Perl 5.005) by creating
190 a new Perl interpreter per thread, and not sharing any data or state between
193 Prior to Perl 5.8, this has only been available to people embedding Perl, and
194 for emulating fork() on Windows.
196 The I<threads> API is loosely based on the old Thread.pm API. It is very
197 important to note that variables are not shared between threads, all variables
198 are by default thread local. To use shared variables one must use
201 It is also important to note that you must enable threads by doing C<use
202 threads> as early as possible in the script itself, and that it is not
203 possible to enable threading inside an C<eval "">, C<do>, C<require>, or
204 C<use>. In particular, if you are intending to share variables with
205 L<threads::shared>, you must C<use threads> before you C<use threads::shared>.
206 (C<threads> will emit a warning if you do it the other way around.)
210 =item $thr = threads->create(FUNCTION, ARGS)
212 This will create a new thread that will begin execution with the specified
213 entry point function, and give it the I<ARGS> list as parameters. It will
214 return the corresponding threads object, or C<undef> if thread creation failed.
216 I<FUNCTION> may either be the name of a function, an anonymous subroutine, or
219 my $thr = threads->create('func_name', ...);
221 my $thr = threads->create(sub { ... }, ...);
223 my $thr = threads->create(\&func, ...);
225 The C<-E<gt>new()> method is an alias for C<-E<gt>create()>.
229 This will wait for the corresponding thread to complete its execution. When
230 the thread finishes, C<-E<gt>join()> will return the return value(s) of the
231 entry point function.
233 The context (void, scalar or list) for the return value(s) for C<-E<gt>join()>
234 is determined at the time of thread creation.
236 # Create thread in list context (implicit)
237 my ($thr1) = threads->create(sub {
238 my @results = qw(a b c);
242 my $thr1 = threads->create({'context' => 'list'},
244 my @results = qw(a b c);
247 # Retrieve list results from thread
248 my @res1 = $thr1->join();
250 # Create thread in scalar context (implicit)
251 my $thr2 = threads->create(sub {
255 # Retrieve scalar result from thread
256 my $res2 = $thr2->join();
258 # Create a thread in void context (explicit)
259 my $thr3 = threads->create({'void' => 1},
260 sub { print("Hello, world\n"); });
261 # Join the thread in void context (i.e., no return value)
264 See L</"THREAD CONTEXT"> for more details.
266 If the program exits without all threads having either been joined or
267 detached, then a warning will be issued.
269 Calling C<-E<gt>join()> or C<-E<gt>detach()> on an already joined thread will
270 cause an error to be thrown.
274 Makes the thread unjoinable, and causes any eventual return value to be
275 discarded. When the program exits, any detached threads that are still
276 running are silently terminated.
278 If the program exits without all threads having either been joined or
279 detached, then a warning will be issued.
281 Calling C<-E<gt>join()> or C<-E<gt>detach()> on an already detached thread
282 will cause an error to be thrown.
284 =item threads->detach()
286 Class method that allows a thread to detach itself.
288 =item threads->exit()
290 The usual method for terminating a thread is to
291 L<return()|perlfunc/"return EXPR"> from the entry point function with the
292 appropriate return value(s).
294 If needed, a thread can be exited at any time by calling
295 C<threads-E<gt>exit()>. This will cause the thread to return C<undef> in a
296 scalar context, or the empty list in a list context.
298 Calling C<die()> in a thread indicates an abnormal exit for the thread. Any
299 C<$SIG{__DIE__}> handler in the thread will be called first, and then the
300 thread will exit with a warning message that will contain any arguments passed
301 in the C<die()> call.
303 Calling C<exit()> in a thread is discouraged, but is equivalent to calling
304 C<threads-E<gt>exit()>.
306 If the desired affect is to truly terminate the application from a thread,
307 then use L<POSIX::_exit()|POSIX/"_exit">, if available.
309 =item threads->self()
311 Class method that allows a thread to obtain its own I<threads> object.
315 Returns the ID of the thread. Thread IDs are unique integers with the main
316 thread in a program being 0, and incrementing by 1 for every thread created.
320 Class method that allows a thread to obtain its own ID.
322 =item threads->object($tid)
324 This will return the I<threads> object for the I<active> thread associated
325 with the specified thread ID. Returns C<undef> if there is no thread
326 associated with the TID, if the thread is joined or detached, if no TID is
327 specified or if the specified TID is undef.
329 =item threads->yield()
331 This is a suggestion to the OS to let this thread yield CPU time to other
332 threads. What actually happens is highly dependent upon the underlying
333 thread implementation.
335 You may do C<use threads qw(yield)>, and then just use C<yield()> in your
338 =item threads->list()
340 =item threads->list(threads::all)
342 =item threads->list(threads::running)
344 =item threads->list(threads::joinable)
346 With no arguments (or using C<threads::all>) and in a list context, returns a
347 list of all non-joined, non-detached I<threads> objects. In a scalar context,
348 returns a count of the same.
350 With a I<true> argument (using C<threads::running>), returns a list of all
351 non-detached I<threads> objects that are still running.
353 With a I<false> argument (using C<threads::joinable>), returns a list of all
354 non-joined, non-detached I<threads> objects that have finished running (i.e.,
355 for which C<-E<gt>join()> will not I<block>).
357 =item $thr1->equal($thr2)
359 Tests if two threads objects are the same thread or not. This is overloaded
360 to the more natural forms:
362 if ($thr1 == $thr2) {
363 print("Threads are the same\n");
366 if ($thr1 != $thr2) {
367 print("Threads differ\n");
370 (Thread comparison is based on thread IDs.)
374 C<async> creates a thread to execute the block immediately following
375 it. This block is treated as an anonymous subroutine, and so must have a
376 semi-colon after the closing brace. Like C<threads->create()>, C<async>
377 returns a I<threads> object.
379 =item $thr->_handle()
381 This I<private> method returns the memory location of the internal thread
382 structure associated with a threads object. For Win32, this is a pointer to
383 the C<HANDLE> value returned by C<CreateThread> (i.e., C<HANDLE *>); for other
384 platforms, it is a pointer to the C<pthread_t> structure used in the
385 C<pthread_create> call (i.e., C<pthread_t *>).
387 This method is of no use for general Perl threads programming. Its intent is
388 to provide other (XS-based) thread modules with the capability to access, and
389 possibly manipulate, the underlying thread structure associated with a Perl
392 =item threads->_handle()
394 Class method that allows a thread to obtain its own I<handle>.
400 The following boolean methods are useful in determining the I<state> of a
405 =item $thr->is_running()
407 Returns true if a thread is still running (i.e., if its entry point function
408 has not yet finished/exited).
410 =item $thr->is_joinable()
412 Returns true if the thread has finished running, is not detached and has not
413 yet been joined. In other works, the thread is ready to be joined and will
416 =item $thr->is_detached()
418 Returns true if the thread has been detached.
420 =item threads->is_detached()
422 Class method that allows a thread to determine whether or not it is detached.
426 =head1 THREAD CONTEXT
428 As with subroutines, the type of value returned from a thread's entry point
429 function may be determined by the thread's I<context>: list, scalar or void.
430 The thread's context is determined at thread creation. This is necessary so
431 that the context is available to the entry point function via
432 L<wantarray()|perlfunc/"wantarray">. The thread may then specify a value of
433 the appropriate type to be returned from C<-E<gt>join()>.
435 =head2 Explicit context
437 Because thread creation and thread joining may occur in different contexts, it
438 may be desirable to state the context explicitly to the thread's entry point
439 function. This may be done by calling C<-E<gt>create()> with a parameter hash
440 as the first argument:
442 my $thr = threads->create({'context' => 'list'}, \&foo);
444 my @results = $thr->join();
446 In the above, the threads object is returned to the parent thread in scalar
447 context, and the thread's entry point function C<foo> will be called in list
448 context such that the parent thread can receive a list from the C<-E<gt>join()>
449 call. Similarly, if you need the threads object, but your thread will not be
450 returning a value (i.e., I<void> context), you would do the following:
452 my $thr = threads->create({'context' => 'void'}, \&foo);
456 The context type may also be used as the I<key> in the parameter hash followed
459 threads->create({'scalar' => 1}, \&foo);
461 my ($thr) = threads->list();
462 my $result = $thr->join();
464 =head2 Implicit context
466 If not explicitly stated, the thread's context is implied from the context
467 of the C<-E<gt>create()> call:
469 # Create thread in list context
470 my ($thr) = threads->create(...);
472 # Create thread in scalar context
473 my $thr = threads->create(...);
475 # Create thread in void context
476 threads->create(...);
478 =head2 $thr->wantarray()
480 This returns the thread's context in the same manner as
481 L<wantarray()|perlfunc/"wantarray">.
483 =head2 threads->wantarray()
485 Class method to return the current thread's context. This is the same as
486 running L<wantarray()|perlfunc/"wantarray"> in the current thread.
488 =head1 THREAD STACK SIZE
490 The default per-thread stack size for different platforms varies
491 significantly, and is almost always far more than is needed for most
492 applications. On Win32, Perl's makefile explicitly sets the default stack to
493 16 MB; on most other platforms, the system default is used, which again may be
494 much larger than is needed.
496 By tuning the stack size to more accurately reflect your application's needs,
497 you may significantly reduce your application's memory usage, and increase the
498 number of simultaneously running threads.
500 N.B., on Windows, Address space allocation granularity is 64 KB, therefore,
501 setting the stack smaller than that on Win32 Perl will not save any more
506 =item threads->get_stack_size();
508 Returns the current default per-thread stack size. The default is zero, which
509 means the system default stack size is currently in use.
511 =item $size = $thr->get_stack_size();
513 Returns the stack size for a particular thread. A return value of zero
514 indicates the system default stack size was used for the thread.
516 =item $old_size = threads->set_stack_size($new_size);
518 Sets a new default per-thread stack size, and returns the previous setting.
520 Some platforms have a minimum thread stack size. Trying to set the stack size
521 below this value will result in a warning, and the minimum stack size will be
524 Some Linux platforms have a maximum stack size. Setting too large of a stack
525 size will cause thread creation to fail.
527 If needed, C<$new_size> will be rounded up to the next multiple of the memory
528 page size (usually 4096 or 8192).
530 Threads created after the stack size is set will then either call
531 C<pthread_attr_setstacksize()> I<(for pthreads platforms)>, or supply the
532 stack size to C<CreateThread()> I<(for Win32 Perl)>.
534 (Obviously, this call does not affect any currently extant threads.)
536 =item use threads ('stack_size' => VALUE);
538 This sets the default per-thread stack size at the start of the application.
540 =item $ENV{'PERL5_ITHREADS_STACK_SIZE'}
542 The default per-thread stack size may be set at the start of the application
543 through the use of the environment variable C<PERL5_ITHREADS_STACK_SIZE>:
545 PERL5_ITHREADS_STACK_SIZE=1048576
546 export PERL5_ITHREADS_STACK_SIZE
547 perl -e'use threads; print(threads->get_stack_size(), "\n")'
549 This value overrides any C<stack_size> parameter given to C<use threads>. Its
550 primary purpose is to permit setting the per-thread stack size for legacy
551 threaded applications.
553 =item threads->create({'stack_size' => VALUE}, FUNCTION, ARGS)
555 The stack size an individual threads may also be specified. This may be done
556 by calling C<-E<gt>create()> with a parameter hash as the first argument:
558 my $thr = threads->create({'stack_size' => 32*4096}, \&foo, @args);
560 =item $thr2 = $thr1->create(FUNCTION, ARGS)
562 This creates a new thread (C<$thr2>) that inherits the stack size from an
563 existing thread (C<$thr1>). This is shorthand for the following:
565 my $stack_size = $thr1->get_stack_size();
566 my $thr2 = threads->create({'stack_size' => $stack_size}, FUNCTION, ARGS);
570 =head1 THREAD SIGNALLING
572 When safe signals is in effect (the default behavior - see L</"Unsafe signals">
573 for more details), then signals may be sent and acted upon by individual
578 =item $thr->kill('SIG...');
580 Sends the specified signal to the thread. Signal names and (positive) signal
581 numbers are the same as those supported by
582 L<kill()|perlfunc/"kill SIGNAL, LIST">. For example, 'SIGTERM', 'TERM' and
583 (depending on the OS) 15 are all valid arguments to C<-E<gt>kill()>.
585 Returns the thread object to allow for method chaining:
587 $thr->kill('SIG...')->join();
591 Signal handlers need to be set up in the threads for the signals they are
592 expected to act upon. Here's an example for I<cancelling> a thread:
598 # Thread 'cancellation' signal handler
599 $SIG{'KILL'} = sub { threads->exit(); };
605 my $thr = threads->create('thr_func');
609 # Signal the thread to terminate, and then detach
610 # it so that it will get cleaned up automatically
611 $thr->kill('KILL')->detach();
613 Here's another simplistic example that illustrates the use of thread
614 signalling in conjunction with a semaphore to provide rudimentary I<suspend>
615 and I<resume> capabilities:
618 use Thread::Semaphore;
624 # Thread 'suspend/resume' signal handler
626 $sema->down(); # Thread suspended
627 $sema->up(); # Thread resumes
633 # Create a semaphore and send it to a thread
634 my $sema = Thread::Semaphore->new();
635 my $thr = threads->create('thr_func', $sema);
643 # Allow the thread to continue
646 CAVEAT: The thread signalling capability provided by this module does not
647 actually send signals via the OS. It I<emulates> signals at the Perl-level
648 such that signal handlers are called in the appropriate thread. For example,
649 sending C<$thr-E<gt>kill('STOP')> does not actually suspend a thread (or the
650 whole process), but does cause a C<$SIG{'STOP'}> handler to be called in that
651 thread (as illustrated above).
653 As such, signals that would normally not be appropriate to use in the
654 C<kill()> command (e.g., C<kill('KILL', $$)>) are okay to use with the
655 C<-E<gt>kill()> method (again, as illustrated above).
657 Correspondingly, sending a signal to a thread does not disrupt the operation
658 the thread is currently working on: The signal will be acted upon after the
659 current operation has completed. For instance, if the thread is I<stuck> on
660 an I/O call, sending it a signal will not cause the I/O call to be interrupted
661 such that the signal is acted up immediately.
667 =item Perl exited with active threads:
669 If the program exits without all threads having either been joined or
670 detached, then this warning will be issued.
672 NOTE: This warning cannot be suppressed using C<no warnings 'threads';> as
675 =item Thread creation failed: pthread_create returned #
677 See the appropriate I<man> page for C<pthread_create> to determine the actual
678 cause for the failure.
680 =item Thread # terminated abnormally: ...
682 A thread terminated in some manner other than just returning from its entry
683 point function. For example, the thread may have terminated using C<die>.
685 =item Using minimum thread stack size of #
687 Some platforms have a minimum thread stack size. Trying to set the stack size
688 below this value will result in the above warning, and the stack size will be
691 =item Thread creation failed: pthread_attr_setstacksize(I<SIZE>) returned 22
693 The specified I<SIZE> exceeds the system's maximum stack size. Use a smaller
694 value for the stack size.
698 If needed, thread warnings can be suppressed by using:
700 no warnings 'threads';
702 in the appropriate scope.
708 =item This Perl not built to support threads
710 The particular copy of Perl that you're trying to use was not built using the
711 C<useithreads> configuration option.
713 Having threads support requires all of Perl and all of the XS modules in the
714 Perl installation to be rebuilt; it is not just a question of adding the
715 L<threads> module (i.e., threaded and non-threaded Perls are binary
718 =item Cannot change stack size of an existing thread
720 The stack size of currently extant threads cannot be changed, therefore, the
721 following results in the above error:
723 $thr->set_stack_size($size);
725 =item Cannot signal threads without safe signals
727 Safe signals must be in effect to use the C<-E<gt>kill()> signalling method.
728 See L</"Unsafe signals"> for more details.
730 =item Unrecognized signal name: ...
732 The particular copy of Perl that you're trying to use does not support the
733 specified signal being used in a C<-E<gt>kill()> call.
741 =item Parent-child threads
743 On some platforms, it might not be possible to destroy I<parent> threads while
744 there are still existing I<child> threads.
746 =item Creating threads inside special blocks
748 Creating threads inside C<BEGIN>, C<CHECK> or C<INIT> blocks should not be
749 relied upon. Depending on the Perl version and the application code, results
750 may range from success, to (apparently harmless) warnings of leaked scalar, or
751 all the way up to crashing of the Perl interpreter.
755 Since Perl 5.8.0, signals have been made safer in Perl by postponing their
756 handling until the interpreter is in a I<safe> state. See
757 L<perl58delta/"Safe Signals"> and L<perlipc/"Deferred Signals (Safe Signals)">
760 Safe signals is the default behavior, and the old, immediate, unsafe
761 signalling behavior is only in effect in the following situations:
765 =item * Perl was been built with C<PERL_OLD_SIGNALS> (see C<perl -V>).
767 =item * The environment variable C<PERL_SIGNALS> is set to C<unsafe> (see L<perlrun/"PERL_SIGNALS">).
769 =item * The module L<Perl::Unsafe::Signals> is used.
773 If unsafe signals is in effect, then signal handling is not thread-safe, and
774 the C<-E<gt>kill()> signalling method cannot be used.
776 =item Returning closures from threads
778 Returning closures from threads should not be relied upon. Depending of the
779 Perl version and the application code, results may range from success, to
780 (apparently harmless) warnings of leaked scalar, or all the way up to crashing
781 of the Perl interpreter.
783 =item Perl Bugs and the CPAN Version of L<threads>
785 Support for threads extents beyond the code in this module (i.e.,
786 F<threads.pm> and F<threads.xs>), and into the Perl iterpreter itself. Older
787 versions of Perl contain bugs that may manifest themselves despite using the
788 latest version of L<threads> from CPAN. There is no workaround for this other
789 than upgrading to the lastest version of Perl.
791 (Before you consider posting a bug report, please consult, and possibly post a
792 message to the discussion forum to see if what you've encountered is a known
803 L<threads> Discussion Forum on CPAN:
804 L<http://www.cpanforum.com/dist/threads>
806 Annotated POD for L<threads>:
807 L<http://annocpan.org/~JDHEDDEN/threads-1.36/threads.pm>
809 L<threads::shared>, L<perlthrtut>
811 L<http://www.perl.com/pub/a/2002/06/11/threads.html> and
812 L<http://www.perl.com/pub/a/2002/09/04/threads.html>
814 Perl threads mailing list:
815 L<http://lists.cpan.org/showlist.cgi?name=iThreads>
817 Stack size discussion:
818 L<http://www.perlmonks.org/?node_id=532956>
822 Artur Bergman E<lt>sky AT crucially DOT netE<gt>
824 threads is released under the same license as Perl.
826 CPAN version produced by Jerry D. Hedden <jdhedden AT cpan DOT org>
828 =head1 ACKNOWLEDGEMENTS
830 Richard Soderberg E<lt>perl AT crystalflame DOT netE<gt> -
831 Helping me out tons, trying to find reasons for races and other weird bugs!
833 Simon Cozens E<lt>simon AT brecon DOT co DOT ukE<gt> -
834 Being there to answer zillions of annoying questions
836 Rocco Caputo E<lt>troc AT netrus DOT netE<gt>
838 Vipul Ved Prakash E<lt>mail AT vipul DOT netE<gt> -
839 Helping with debugging
841 Dean Arnold E<lt>darnold AT presicient DOT comE<gt> -