1threads(3) User Contributed Perl Documentation threads(3)
2
6 threads - Perl interpreter-based threads
7
9 This document describes threads version 1.87
10
12 use threads ('yield',
13 'stack_size' => 64*4096,
14 'exit' => 'threads_only',
15 'stringify');
16 sub start_thread {
18 my @args = @_;
19 print('Thread started: ', join(' ', @args), "\n");
20 }
21 my $thr = threads->create('start_thread', 'argument');
22 $thr->join();
23 threads->create(sub { print("I am a thread\n"); })->join();
25 my $thr2 = async { foreach (@files) { ... } };
27 $thr2->join();
28 if (my $err = $thr2->error()) {
29 warn("Thread error: $err\n");
30 }
31 # Invoke thread in list context (implicit) so it can return a list
33 my ($thr) = threads->create(sub { return (qw/a b c/); });
34 # or specify list context explicitly
35 my $thr = threads->create({'context' => 'list'},
36 sub { return (qw/a b c/); });
37 my @results = $thr->join();
38 $thr->detach();
40 # Get a thread's object
42 $thr = threads->self();
43 $thr = threads->object($tid);
44 # Get a thread's ID
46 $tid = threads->tid();
47 $tid = $thr->tid();
48 $tid = "$thr";
49 # Give other threads a chance to run
51 threads->yield();
52 yield();
53 # Lists of non-detached threads
55 my @threads = threads->list();
56 my $thread_count = threads->list();
57 my @running = threads->list(threads::running);
59 my @joinable = threads->list(threads::joinable);
60 # Test thread objects
62 if ($thr1 == $thr2) {
63 ...
64 }
65 # Manage thread stack size
67 $stack_size = threads->get_stack_size();
68 $old_size = threads->set_stack_size(32*4096);
69 # Create a thread with a specific context and stack size
71 my $thr = threads->create({ 'context' => 'list',
72 'stack_size' => 32*4096,
73 'exit' => 'thread_only' },
74 \&foo);
75 # Get thread's context
77 my $wantarray = $thr->wantarray();
78 # Check thread's state
80 if ($thr->is_running()) {
81 sleep(1);
82 }
83 if ($thr->is_joinable()) {
84 $thr->join();
85 }
86 # Send a signal to a thread
88 $thr->kill('SIGUSR1');
89 # Exit a thread
91 threads->exit();
92
94 Since Perl 5.8, thread programming has been available using a model
95 called interpreter threads which provides a new Perl interpreter for
96 each thread, and, by default, results in no data or state information
97 being shared between threads.
98 (Prior to Perl 5.8, 5005threads was available through the "Thread.pm"
100 API. This threading model has been deprecated, and was removed as of
101 Perl 5.10.0.)
102 As just mentioned, all variables are, by default, thread local. To use
104 shared variables, you need to also load threads::shared:
105 use threads;
107 use threads::shared;
108 When loading threads::shared, you must "use threads" before you "use
110 threads::shared". ("threads" will emit a warning if you do it the
111 other way around.)
112 It is strongly recommended that you enable threads via "use threads" as
114 early as possible in your script.
115 If needed, scripts can be written so as to run on both threaded and
117 non-threaded Perls:
118 my $can_use_threads = eval 'use threads; 1';
120 if ($can_use_threads) {
121 # Do processing using threads
122 ...
123 } else {
124 # Do it without using threads
125 ...
126 }
127 $thr = threads->create(FUNCTION, ARGS)
129 This will create a new thread that will begin execution with the
130 specified entry point function, and give it the ARGS list as
131 parameters. It will return the corresponding threads object, or
132 "undef" if thread creation failed.
133 FUNCTION may either be the name of a function, an anonymous
135 subroutine, or a code ref.
136 my $thr = threads->create('func_name', ...);
138 # or
139 my $thr = threads->create(sub { ... }, ...);
140 # or
141 my $thr = threads->create(\&func, ...);
142 The "->new()" method is an alias for "->create()".
144 $thr->join()
146 This will wait for the corresponding thread to complete its
147 execution. When the thread finishes, "->join()" will return the
148 return value(s) of the entry point function.
149 The context (void, scalar or list) for the return value(s) for
151 "->join()" is determined at the time of thread creation.
152 # Create thread in list context (implicit)
154 my ($thr1) = threads->create(sub {
155 my @results = qw(a b c);
156 return (@results);
157 });
158 # or (explicit)
159 my $thr1 = threads->create({'context' => 'list'},
160 sub {
161 my @results = qw(a b c);
162 return (@results);
163 });
164 # Retrieve list results from thread
165 my @res1 = $thr1->join();
166 # Create thread in scalar context (implicit)
168 my $thr2 = threads->create(sub {
169 my $result = 42;
170 return ($result);
171 });
172 # Retrieve scalar result from thread
173 my $res2 = $thr2->join();
174 # Create a thread in void context (explicit)
176 my $thr3 = threads->create({'void' => 1},
177 sub { print("Hello, world\n"); });
178 # Join the thread in void context (i.e., no return value)
179 $thr3->join();
180 See "THREAD CONTEXT" for more details.
182 If the program exits without all threads having either been joined
184 or detached, then a warning will be issued.
185 Calling "->join()" or "->detach()" on an already joined thread will
187 cause an error to be thrown.
188 $thr->detach()
190 Makes the thread unjoinable, and causes any eventual return value
191 to be discarded. When the program exits, any detached threads that
192 are still running are silently terminated.
193 If the program exits without all threads having either been joined
195 or detached, then a warning will be issued.
196 Calling "->join()" or "->detach()" on an already detached thread
198 will cause an error to be thrown.
199 threads->detach()
201 Class method that allows a thread to detach itself.
202 threads->self()
204 Class method that allows a thread to obtain its own threads object.
205 $thr->tid()
207 Returns the ID of the thread. Thread IDs are unique integers with
208 the main thread in a program being 0, and incrementing by 1 for
209 every thread created.
210 threads->tid()
212 Class method that allows a thread to obtain its own ID.
213 "$thr"
215 If you add the "stringify" import option to your "use threads"
216 declaration, then using a threads object in a string or a string
217 context (e.g., as a hash key) will cause its ID to be used as the
218 value:
219 use threads qw(stringify);
221 my $thr = threads->create(...);
223 print("Thread $thr started...\n"); # Prints out: Thread 1 started...
224 threads->object($tid)
226 This will return the threads object for the active thread
227 associated with the specified thread ID. If $tid is the value for
228 the current thread, then this call works the same as "->self()".
229 Otherwise, returns "undef" if there is no thread associated with
230 the TID, if the thread is joined or detached, if no TID is
231 specified or if the specified TID is undef.
232 threads->yield()
234 This is a suggestion to the OS to let this thread yield CPU time to
235 other threads. What actually happens is highly dependent upon the
236 underlying thread implementation.
237 You may do "use threads qw(yield)", and then just use "yield()" in
239 your code.
240 threads->list()
242 threads->list(threads::all)
243 threads->list(threads::running)
244 threads->list(threads::joinable)
245 With no arguments (or using "threads::all") and in a list context,
246 returns a list of all non-joined, non-detached threads objects. In
247 a scalar context, returns a count of the same.
248 With a true argument (using "threads::running"), returns a list of
250 all non-joined, non-detached threads objects that are still
251 running.
252 With a false argument (using "threads::joinable"), returns a list
254 of all non-joined, non-detached threads objects that have finished
255 running (i.e., for which "->join()" will not block).
256 $thr1->equal($thr2)
258 Tests if two threads objects are the same thread or not. This is
259 overloaded to the more natural forms:
260 if ($thr1 == $thr2) {
262 print("Threads are the same\n");
263 }
264 # or
265 if ($thr1 != $thr2) {
266 print("Threads differ\n");
267 }
268 (Thread comparison is based on thread IDs.)
270 async BLOCK;
272 "async" creates a thread to execute the block immediately following
273 it. This block is treated as an anonymous subroutine, and so must
274 have a semicolon after the closing brace. Like
275 "threads->create()", "async" returns a threads object.
276 $thr->error()
278 Threads are executed in an "eval" context. This method will return
279 "undef" if the thread terminates normally. Otherwise, it returns
280 the value of $@ associated with the thread's execution status in
281 its "eval" context.
282 $thr->_handle()
284 This private method returns the memory location of the internal
285 thread structure associated with a threads object. For Win32, this
286 is a pointer to the "HANDLE" value returned by "CreateThread"
287 (i.e., "HANDLE *"); for other platforms, it is a pointer to the
288 "pthread_t" structure used in the "pthread_create" call (i.e.,
289 "pthread_t *").
290 This method is of no use for general Perl threads programming. Its
292 intent is to provide other (XS-based) thread modules with the
293 capability to access, and possibly manipulate, the underlying
294 thread structure associated with a Perl thread.
295 threads->_handle()
297 Class method that allows a thread to obtain its own handle.
298
300 The usual method for terminating a thread is to return() from the entry
301 point function with the appropriate return value(s).
302 threads->exit()
304 If needed, a thread can be exited at any time by calling
305 "threads->exit()". This will cause the thread to return "undef" in
306 a scalar context, or the empty list in a list context.
307 When called from the main thread, this behaves the same as exit(0).
309 threads->exit(status)
311 When called from a thread, this behaves like "threads->exit()"
312 (i.e., the exit status code is ignored).
313 When called from the main thread, this behaves the same as
315 "exit(status)".
316 die()
318 Calling "die()" in a thread indicates an abnormal exit for the
319 thread. Any $SIG{__DIE__} handler in the thread will be called
320 first, and then the thread will exit with a warning message that
321 will contain any arguments passed in the "die()" call.
322 exit(status)
324 Calling exit() inside a thread causes the whole application to
325 terminate. Because of this, the use of "exit()" inside threaded
326 code, or in modules that might be used in threaded applications, is
327 strongly discouraged.
328 If "exit()" really is needed, then consider using the following:
330 threads->exit() if threads->can('exit'); # Thread friendly
332 exit(status);
333 use threads 'exit' => 'threads_only'
335 This globally overrides the default behavior of calling "exit()"
336 inside a thread, and effectively causes such calls to behave the
337 same as "threads->exit()". In other words, with this setting,
338 calling "exit()" causes only the thread to terminate.
339 Because of its global effect, this setting should not be used
341 inside modules or the like.
342 The main thread is unaffected by this setting.
344 threads->create({'exit' => 'thread_only'}, ...)
346 This overrides the default behavior of "exit()" inside the newly
347 created thread only.
348 $thr->set_thread_exit_only(boolean)
350 This can be used to change the exit thread only behavior for a
351 thread after it has been created. With a true argument, "exit()"
352 will cause only the thread to exit. With a false argument,
353 "exit()" will terminate the application.
354 The main thread is unaffected by this call.
356 threads->set_thread_exit_only(boolean)
358 Class method for use inside a thread to change its own behavior for
359 "exit()".
360 The main thread is unaffected by this call.
362
364 The following boolean methods are useful in determining the state of a
365 thread.
366 $thr->is_running()
368 Returns true if a thread is still running (i.e., if its entry point
369 function has not yet finished or exited).
370 $thr->is_joinable()
372 Returns true if the thread has finished running, is not detached
373 and has not yet been joined. In other words, the thread is ready
374 to be joined, and a call to "$thr->join()" will not block.
375 $thr->is_detached()
377 Returns true if the thread has been detached.
378 threads->is_detached()
380 Class method that allows a thread to determine whether or not it is
381 detached.
382
384 As with subroutines, the type of value returned from a thread's entry
385 point function may be determined by the thread's context: list, scalar
386 or void. The thread's context is determined at thread creation. This
387 is necessary so that the context is available to the entry point
388 function via wantarray(). The thread may then specify a value of the
389 appropriate type to be returned from "->join()".
390 Explicit context
392 Because thread creation and thread joining may occur in different
393 contexts, it may be desirable to state the context explicitly to the
394 thread's entry point function. This may be done by calling
395 "->create()" with a hash reference as the first argument:
396 my $thr = threads->create({'context' => 'list'}, \&foo);
398 ...
399 my @results = $thr->join();
400 In the above, the threads object is returned to the parent thread in
402 scalar context, and the thread's entry point function "foo" will be
403 called in list (array) context such that the parent thread can receive
404 a list (array) from the "->join()" call. ('array' is synonymous with
405 'list'.)
406 Similarly, if you need the threads object, but your thread will not be
408 returning a value (i.e., void context), you would do the following:
409 my $thr = threads->create({'context' => 'void'}, \&foo);
411 ...
412 $thr->join();
413 The context type may also be used as the key in the hash reference
415 followed by a true value:
416 threads->create({'scalar' => 1}, \&foo);
418 ...
419 my ($thr) = threads->list();
420 my $result = $thr->join();
421 Implicit context
423 If not explicitly stated, the thread's context is implied from the
424 context of the "->create()" call:
425 # Create thread in list context
427 my ($thr) = threads->create(...);
428 # Create thread in scalar context
430 my $thr = threads->create(...);
431 # Create thread in void context
433 threads->create(...);
434 $thr->wantarray()
436 This returns the thread's context in the same manner as wantarray().
437 threads->wantarray()
439 Class method to return the current thread's context. This returns the
440 same value as running wantarray() inside the current thread's entry
441 point function.
442
444 The default per-thread stack size for different platforms varies
445 significantly, and is almost always far more than is needed for most
446 applications. On Win32, Perl's makefile explicitly sets the default
447 stack to 16 MB; on most other platforms, the system default is used,
448 which again may be much larger than is needed.
449 By tuning the stack size to more accurately reflect your application's
451 needs, you may significantly reduce your application's memory usage,
452 and increase the number of simultaneously running threads.
453 Note that on Windows, address space allocation granularity is 64 KB,
455 therefore, setting the stack smaller than that on Win32 Perl will not
456 save any more memory.
457 threads->get_stack_size();
459 Returns the current default per-thread stack size. The default is
460 zero, which means the system default stack size is currently in
461 use.
462 $size = $thr->get_stack_size();
464 Returns the stack size for a particular thread. A return value of
465 zero indicates the system default stack size was used for the
466 thread.
467 $old_size = threads->set_stack_size($new_size);
469 Sets a new default per-thread stack size, and returns the previous
470 setting.
471 Some platforms have a minimum thread stack size. Trying to set the
473 stack size below this value will result in a warning, and the
474 minimum stack size will be used.
475 Some Linux platforms have a maximum stack size. Setting too large
477 of a stack size will cause thread creation to fail.
478 If needed, $new_size will be rounded up to the next multiple of the
480 memory page size (usually 4096 or 8192).
481 Threads created after the stack size is set will then either call
483 "pthread_attr_setstacksize()" (for pthreads platforms), or supply
484 the stack size to "CreateThread()" (for Win32 Perl).
485 (Obviously, this call does not affect any currently extant
487 threads.)
488 use threads ('stack_size' => VALUE);
490 This sets the default per-thread stack size at the start of the
491 application.
492 $ENV{'PERL5_ITHREADS_STACK_SIZE'}
494 The default per-thread stack size may be set at the start of the
495 application through the use of the environment variable
496 "PERL5_ITHREADS_STACK_SIZE":
497 PERL5_ITHREADS_STACK_SIZE=1048576
499 export PERL5_ITHREADS_STACK_SIZE
500 perl -e'use threads; print(threads->get_stack_size(), "\n")'
501 This value overrides any "stack_size" parameter given to "use
503 threads". Its primary purpose is to permit setting the per-thread
504 stack size for legacy threaded applications.
505 threads->create({'stack_size' => VALUE}, FUNCTION, ARGS)
507 To specify a particular stack size for any individual thread, call
508 "->create()" with a hash reference as the first argument:
509 my $thr = threads->create({'stack_size' => 32*4096}, \&foo, @args);
511 $thr2 = $thr1->create(FUNCTION, ARGS)
513 This creates a new thread ($thr2) that inherits the stack size from
514 an existing thread ($thr1). This is shorthand for the following:
515 my $stack_size = $thr1->get_stack_size();
517 my $thr2 = threads->create({'stack_size' => $stack_size}, FUNCTION, ARGS);
518
520 When safe signals is in effect (the default behavior - see "Unsafe
521 signals" for more details), then signals may be sent and acted upon by
522 individual threads.
523 $thr->kill('SIG...');
525 Sends the specified signal to the thread. Signal names and
526 (positive) signal numbers are the same as those supported by
527 kill(). For example, 'SIGTERM', 'TERM' and (depending on the OS)
528 15 are all valid arguments to "->kill()".
529 Returns the thread object to allow for method chaining:
531 $thr->kill('SIG...')->join();
533 Signal handlers need to be set up in the threads for the signals they
535 are expected to act upon. Here's an example for cancelling a thread:
536 use threads;
538 sub thr_func
540 {
541 # Thread 'cancellation' signal handler
542 $SIG{'KILL'} = sub { threads->exit(); };
543 ...
545 }
546 # Create a thread
548 my $thr = threads->create('thr_func');
549 ...
551 # Signal the thread to terminate, and then detach
553 # it so that it will get cleaned up automatically
554 $thr->kill('KILL')->detach();
555 Here's another simplistic example that illustrates the use of thread
557 signalling in conjunction with a semaphore to provide rudimentary
558 suspend and resume capabilities:
559 use threads;
561 use Thread::Semaphore;
562 sub thr_func
564 {
565 my $sema = shift;
566 # Thread 'suspend/resume' signal handler
568 $SIG{'STOP'} = sub {
569 $sema->down(); # Thread suspended
570 $sema->up(); # Thread resumes
571 };
572 ...
574 }
575 # Create a semaphore and pass it to a thread
577 my $sema = Thread::Semaphore->new();
578 my $thr = threads->create('thr_func', $sema);
579 # Suspend the thread
581 $sema->down();
582 $thr->kill('STOP');
583 ...
585 # Allow the thread to continue
587 $sema->up();
588 CAVEAT: The thread signalling capability provided by this module does
590 not actually send signals via the OS. It emulates signals at the Perl-
591 level such that signal handlers are called in the appropriate thread.
592 For example, sending "$thr->kill('STOP')" does not actually suspend a
593 thread (or the whole process), but does cause a $SIG{'STOP'} handler to
594 be called in that thread (as illustrated above).
595 As such, signals that would normally not be appropriate to use in the
597 "kill()" command (e.g., "kill('KILL', $$)") are okay to use with the
598 "->kill()" method (again, as illustrated above).
599 Correspondingly, sending a signal to a thread does not disrupt the
601 operation the thread is currently working on: The signal will be acted
602 upon after the current operation has completed. For instance, if the
603 thread is stuck on an I/O call, sending it a signal will not cause the
604 I/O call to be interrupted such that the signal is acted up
605 immediately.
606 Sending a signal to a terminated/finished thread is ignored.
608
610 Perl exited with active threads:
611 If the program exits without all threads having either been joined
612 or detached, then this warning will be issued.
613 NOTE: If the main thread exits, then this warning cannot be
615 suppressed using "no warnings 'threads';" as suggested below.
616 Thread creation failed: pthread_create returned #
618 See the appropriate man page for "pthread_create" to determine the
619 actual cause for the failure.
620 Thread # terminated abnormally: ...
622 A thread terminated in some manner other than just returning from
623 its entry point function, or by using "threads->exit()". For
624 example, the thread may have terminated because of an error, or by
625 using "die".
626 Using minimum thread stack size of #
628 Some platforms have a minimum thread stack size. Trying to set the
629 stack size below this value will result in the above warning, and
630 the stack size will be set to the minimum.
631 Thread creation failed: pthread_attr_setstacksize(SIZE) returned 22
633 The specified SIZE exceeds the system's maximum stack size. Use a
634 smaller value for the stack size.
635 If needed, thread warnings can be suppressed by using:
637 no warnings 'threads';
639 in the appropriate scope.
641
643 This Perl not built to support threads
644 The particular copy of Perl that you're trying to use was not built
645 using the "useithreads" configuration option.
646 Having threads support requires all of Perl and all of the XS
648 modules in the Perl installation to be rebuilt; it is not just a
649 question of adding the threads module (i.e., threaded and non-
650 threaded Perls are binary incompatible).
651 Cannot change stack size of an existing thread
653 The stack size of currently extant threads cannot be changed,
654 therefore, the following results in the above error:
655 $thr->set_stack_size($size);
657 Cannot signal threads without safe signals
659 Safe signals must be in effect to use the "->kill()" signalling
660 method. See "Unsafe signals" for more details.
661 Unrecognized signal name: ...
663 The particular copy of Perl that you're trying to use does not
664 support the specified signal being used in a "->kill()" call.
665
667 Before you consider posting a bug report, please consult, and possibly
668 post a message to the discussion forum to see if what you've
669 encountered is a known problem.
670 Thread-safe modules
672 See "Making your module threadsafe" in perlmod when creating
673 modules that may be used in threaded applications, especially if
674 those modules use non-Perl data, or XS code.
675 Using non-thread-safe modules
677 Unfortunately, you may encounter Perl modules that are not thread-
678 safe. For example, they may crash the Perl interpreter during
679 execution, or may dump core on termination. Depending on the
680 module and the requirements of your application, it may be possible
681 to work around such difficulties.
682 If the module will only be used inside a thread, you can try
684 loading the module from inside the thread entry point function
685 using "require" (and "import" if needed):
686 sub thr_func
688 {
689 require Unsafe::Module
690 # Unsafe::Module->import(...);
691 ....
693 }
694 If the module is needed inside the main thread, try modifying your
696 application so that the module is loaded (again using "require" and
697 "->import()") after any threads are started, and in such a way that
698 no other threads are started afterwards.
699 If the above does not work, or is not adequate for your
701 application, then file a bug report on <http://rt.cpan.org/Public/>
702 against the problematic module.
703 Memory consumption
705 On most systems, frequent and continual creation and destruction of
706 threads can lead to ever-increasing growth in the memory footprint
707 of the Perl interpreter. While it is simple to just launch threads
708 and then "->join()" or "->detach()" them, for long-lived
709 applications, it is better to maintain a pool of threads, and to
710 reuse them for the work needed, using queues to notify threads of
711 pending work. The CPAN distribution of this module contains a
712 simple example (examples/pool_reuse.pl) illustrating the creation,
713 use and monitoring of a pool of reusable threads.
714 Current working directory
716 On all platforms except MSWin32, the setting for the current
717 working directory is shared among all threads such that changing it
718 in one thread (e.g., using "chdir()") will affect all the threads
719 in the application.
720 On MSWin32, each thread maintains its own the current working
722 directory setting.
723 Environment variables
725 Currently, on all platforms except MSWin32, all system calls (e.g.,
726 using "system()" or back-ticks) made from threads use the
727 environment variable settings from the main thread. In other
728 words, changes made to %ENV in a thread will not be visible in
729 system calls made by that thread.
730 To work around this, set environment variables as part of the
732 system call. For example:
733 my $msg = 'hello';
735 system("FOO=$msg; echo \$FOO"); # Outputs 'hello' to STDOUT
736 On MSWin32, each thread maintains its own set of environment
738 variables.
739 Catching signals
741 Signals are caught by the main thread (thread ID = 0) of a script.
742 Therefore, setting up signal handlers in threads for purposes other
743 than "THREAD SIGNALLING" as documented above will not accomplish
744 what is intended.
745 This is especially true if trying to catch "SIGALRM" in a thread.
747 To handle alarms in threads, set up a signal handler in the main
748 thread, and then use "THREAD SIGNALLING" to relay the signal to the
749 thread:
750 # Create thread with a task that may time out
752 my $thr->create(sub {
753 threads->yield();
754 eval {
755 $SIG{ALRM} = sub { die("Timeout\n"); };
756 alarm(10);
757 ... # Do work here
758 alarm(0);
759 };
760 if ($@ =~ /Timeout/) {
761 warn("Task in thread timed out\n");
762 }
763 };
764 # Set signal handler to relay SIGALRM to thread
766 $SIG{ALRM} = sub { $thr->kill('ALRM') };
767 ... # Main thread continues working
769 Parent-child threads
771 On some platforms, it might not be possible to destroy parent
772 threads while there are still existing child threads.
773 Creating threads inside special blocks
775 Creating threads inside "BEGIN", "CHECK" or "INIT" blocks should
776 not be relied upon. Depending on the Perl version and the
777 application code, results may range from success, to (apparently
778 harmless) warnings of leaked scalar, or all the way up to crashing
779 of the Perl interpreter.
780 Unsafe signals
782 Since Perl 5.8.0, signals have been made safer in Perl by
783 postponing their handling until the interpreter is in a safe state.
784 See "Safe Signals" in perl58delta and "Deferred Signals (Safe
785 Signals)" in perlipc for more details.
786 Safe signals is the default behavior, and the old, immediate,
788 unsafe signalling behavior is only in effect in the following
789 situations:
790 · Perl has been built with "PERL_OLD_SIGNALS" (see "perl -V").
792 · The environment variable "PERL_SIGNALS" is set to "unsafe" (see
794 "PERL_SIGNALS" in perlrun).
795 · The module Perl::Unsafe::Signals is used.
797 If unsafe signals is in effect, then signal handling is not thread-
799 safe, and the "->kill()" signalling method cannot be used.
800 Returning closures from threads
802 Returning closures from threads should not be relied upon.
803 Depending on the Perl version and the application code, results may
804 range from success, to (apparently harmless) warnings of leaked
805 scalar, or all the way up to crashing of the Perl interpreter.
806 Returning objects from threads
808 Returning objects from threads does not work. Depending on the
809 classes involved, you may be able to work around this by returning
810 a serialized version of the object (e.g., using Data::Dumper or
811 Storable), and then reconstituting it in the joining thread. If
812 you're using Perl 5.10.0 or later, and if the class supports shared
813 objects, you can pass them via shared queues.
814 END blocks in threads
816 It is possible to add END blocks to threads by using require or
817 eval with the appropriate code. These "END" blocks will then be
818 executed when the thread's interpreter is destroyed (i.e., either
819 during a "->join()" call, or at program termination).
820 However, calling any threads methods in such an "END" block will
822 most likely fail (e.g., the application may hang, or generate an
823 error) due to mutexes that are needed to control functionality
824 within the threads module.
825 For this reason, the use of "END" blocks in threads is strongly
827 discouraged.
828 Open directory handles
830 In perl 5.14 and higher, on systems other than Windows that do not
831 support the "fchdir" C function, directory handles (see opendir)
832 will not be copied to new threads. You can use the "d_fchdir"
833 variable in Config.pm to determine whether your system supports it.
834 In prior perl versions, spawning threads with open directory
836 handles would crash the interpreter. [perl #75154]
837 <http://rt.perl.org/rt3/Public/Bug/Display.html?id=75154>
838 Perl Bugs and the CPAN Version of threads
840 Support for threads extends beyond the code in this module (i.e.,
841 threads.pm and threads.xs), and into the Perl interpreter itself.
842 Older versions of Perl contain bugs that may manifest themselves
843 despite using the latest version of threads from CPAN. There is no
844 workaround for this other than upgrading to the latest version of
845 Perl.
846 Even with the latest version of Perl, it is known that certain
848 constructs with threads may result in warning messages concerning
849 leaked scalars or unreferenced scalars. However, such warnings are
850 harmless, and may safely be ignored.
851 You can search for threads related bug reports at
853 <http://rt.cpan.org/Public/>. If needed submit any new bugs,
854 problems, patches, etc. to:
855 <http://rt.cpan.org/Public/Dist/Display.html?Name=threads>
856
858 Perl 5.8.0 or later
859
861 threads Discussion Forum on CPAN:
862 <http://www.cpanforum.com/dist/threads>
863 threads::shared, perlthrtut
865 <http://www.perl.com/pub/a/2002/06/11/threads.html> and
867 <http://www.perl.com/pub/a/2002/09/04/threads.html>
868 Perl threads mailing list: <http://lists.perl.org/list/ithreads.html>
870 Stack size discussion: <http://www.perlmonks.org/?node_id=532956>
872
874 Artur Bergman <sky AT crucially DOT net>
875 CPAN version produced by Jerry D. Hedden <jdhedden AT cpan DOT org>
877
879 threads is released under the same license as Perl.
880
882 Richard Soderberg <perl AT crystalflame DOT net> - Helping me out tons,
883 trying to find reasons for races and other weird bugs!
884 Simon Cozens <simon AT brecon DOT co DOT uk> - Being there to answer
886 zillions of annoying questions
887 Rocco Caputo <troc AT netrus DOT net>
889 Vipul Ved Prakash <mail AT vipul DOT net> - Helping with debugging
891 Dean Arnold <darnold AT presicient DOT com> - Stack size API
893perl v5.16.3 2013-05-29 threads(3)