1threads(3pm)           Perl Programmers Reference Guide           threads(3pm)
2
3
4

NAME

6       threads - Perl interpreter-based threads
7

VERSION

9       This document describes threads version 1.82
10

SYNOPSIS

12           use threads ('yield',
13                        'stack_size' => 64*4096,
14                        'exit' => 'threads_only',
15                        'stringify');
16
17           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
24           threads->create(sub { print("I am a thread\n"); })->join();
25
26           my $thr2 = async { foreach (@files) { ... } };
27           $thr2->join();
28           if (my $err = $thr2->error()) {
29               warn("Thread error: $err\n");
30           }
31
32           # 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
39           $thr->detach();
40
41           # Get a thread's object
42           $thr = threads->self();
43           $thr = threads->object($tid);
44
45           # Get a thread's ID
46           $tid = threads->tid();
47           $tid = $thr->tid();
48           $tid = "$thr";
49
50           # Give other threads a chance to run
51           threads->yield();
52           yield();
53
54           # Lists of non-detached threads
55           my @threads = threads->list();
56           my $thread_count = threads->list();
57
58           my @running = threads->list(threads::running);
59           my @joinable = threads->list(threads::joinable);
60
61           # Test thread objects
62           if ($thr1 == $thr2) {
63               ...
64           }
65
66           # Manage thread stack size
67           $stack_size = threads->get_stack_size();
68           $old_size = threads->set_stack_size(32*4096);
69
70           # 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
76           # Get thread's context
77           my $wantarray = $thr->wantarray();
78
79           # Check thread's state
80           if ($thr->is_running()) {
81               sleep(1);
82           }
83           if ($thr->is_joinable()) {
84               $thr->join();
85           }
86
87           # Send a signal to a thread
88           $thr->kill('SIGUSR1');
89
90           # Exit a thread
91           threads->exit();
92

DESCRIPTION

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
99       (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
103       As just mentioned, all variables are, by default, thread local.  To use
104       shared variables, you need to also load threads::shared:
105
106           use threads;
107           use threads::shared;
108
109       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
113       It is strongly recommended that you enable threads via "use threads" as
114       early as possible in your script.
115
116       If needed, scripts can be written so as to run on both threaded and
117       non-threaded Perls:
118
119           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
128       $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
134           FUNCTION may either be the name of a function, an anonymous
135           subroutine, or a code ref.
136
137               my $thr = threads->create('func_name', ...);
138                   # or
139               my $thr = threads->create(sub { ... }, ...);
140                   # or
141               my $thr = threads->create(\&func, ...);
142
143           The "->new()" method is an alias for "->create()".
144
145       $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
150           The context (void, scalar or list) for the return value(s) for
151           "->join()" is determined at the time of thread creation.
152
153               # 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
167               # 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
175               # 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
181           See "THREAD CONTEXT" for more details.
182
183           If the program exits without all threads having either been joined
184           or detached, then a warning will be issued.
185
186           Calling "->join()" or "->detach()" on an already joined thread will
187           cause an error to be thrown.
188
189       $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
194           If the program exits without all threads having either been joined
195           or detached, then a warning will be issued.
196
197           Calling "->join()" or "->detach()" on an already detached thread
198           will cause an error to be thrown.
199
200       threads->detach()
201           Class method that allows a thread to detach itself.
202
203       threads->self()
204           Class method that allows a thread to obtain its own threads object.
205
206       $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
211       threads->tid()
212           Class method that allows a thread to obtain its own ID.
213
214       "$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
220               use threads qw(stringify);
221
222               my $thr = threads->create(...);
223               print("Thread $thr started...\n");  # Prints out: Thread 1 started...
224
225       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
233       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
238           You may do "use threads qw(yield)", and then just use "yield()" in
239           your code.
240
241       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
249           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
253           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
257       $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
261               if ($thr1 == $thr2) {
262                   print("Threads are the same\n");
263               }
264               # or
265               if ($thr1 != $thr2) {
266                   print("Threads differ\n");
267               }
268
269           (Thread comparison is based on thread IDs.)
270
271       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
277       $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
283       $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
291           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
296       threads->_handle()
297           Class method that allows a thread to obtain its own handle.
298

EXITING A THREAD

300       The usual method for terminating a thread is to return() from the entry
301       point function with the appropriate return value(s).
302
303       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
308           When called from the main thread, this behaves the same as exit(0).
309
310       threads->exit(status)
311           When called from a thread, this behaves like "threads->exit()"
312           (i.e., the exit status code is ignored).
313
314           When called from the main thread, this behaves the same as
315           "exit(status)".
316
317       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
323       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
329           If "exit()" really is needed, then consider using the following:
330
331               threads->exit() if threads->can('exit');   # Thread friendly
332               exit(status);
333
334       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
340           Because of its global effect, this setting should not be used
341           inside modules or the like.
342
343           The main thread is unaffected by this setting.
344
345       threads->create({'exit' => 'thread_only'}, ...)
346           This overrides the default behavior of "exit()" inside the newly
347           created thread only.
348
349       $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
355           The main thread is unaffected by this call.
356
357       threads->set_thread_exit_only(boolean)
358           Class method for use inside a thread to change its own behavior for
359           "exit()".
360
361           The main thread is unaffected by this call.
362

THREAD STATE

364       The following boolean methods are useful in determining the state of a
365       thread.
366
367       $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
371       $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
376       $thr->is_detached()
377           Returns true if the thread has been detached.
378
379       threads->is_detached()
380           Class method that allows a thread to determine whether or not it is
381           detached.
382

THREAD CONTEXT

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
391   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
397           my $thr = threads->create({'context' => 'list'}, \&foo);
398           ...
399           my @results = $thr->join();
400
401       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
407       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
410           my $thr = threads->create({'context' => 'void'}, \&foo);
411           ...
412           $thr->join();
413
414       The context type may also be used as the key in the hash reference
415       followed by a true value:
416
417           threads->create({'scalar' => 1}, \&foo);
418           ...
419           my ($thr) = threads->list();
420           my $result = $thr->join();
421
422   Implicit context
423       If not explicitly stated, the thread's context is implied from the
424       context of the "->create()" call:
425
426           # Create thread in list context
427           my ($thr) = threads->create(...);
428
429           # Create thread in scalar context
430           my $thr = threads->create(...);
431
432           # Create thread in void context
433           threads->create(...);
434
435   $thr->wantarray()
436       This returns the thread's context in the same manner as wantarray().
437
438   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

THREAD STACK SIZE

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
450       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
454       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
458       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
463       $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
468       $old_size = threads->set_stack_size($new_size);
469           Sets a new default per-thread stack size, and returns the previous
470           setting.
471
472           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
476           Some Linux platforms have a maximum stack size.  Setting too large
477           of a stack size will cause thread creation to fail.
478
479           If needed, $new_size will be rounded up to the next multiple of the
480           memory page size (usually 4096 or 8192).
481
482           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
486           (Obviously, this call does not affect any currently extant
487           threads.)
488
489       use threads ('stack_size' => VALUE);
490           This sets the default per-thread stack size at the start of the
491           application.
492
493       $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
498               PERL5_ITHREADS_STACK_SIZE=1048576
499               export PERL5_ITHREADS_STACK_SIZE
500               perl -e'use threads; print(threads->get_stack_size(), "\n")'
501
502           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
506       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
510               my $thr = threads->create({'stack_size' => 32*4096}, \&foo, @args);
511
512       $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
516               my $stack_size = $thr1->get_stack_size();
517               my $thr2 = threads->create({'stack_size' => $stack_size}, FUNCTION, ARGS);
518

THREAD SIGNALLING

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
524       $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
530           Returns the thread object to allow for method chaining:
531
532               $thr->kill('SIG...')->join();
533
534       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
537           use threads;
538
539           sub thr_func
540           {
541               # Thread 'cancellation' signal handler
542               $SIG{'KILL'} = sub { threads->exit(); };
543
544               ...
545           }
546
547           # Create a thread
548           my $thr = threads->create('thr_func');
549
550           ...
551
552           # Signal the thread to terminate, and then detach
553           # it so that it will get cleaned up automatically
554           $thr->kill('KILL')->detach();
555
556       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
560           use threads;
561           use Thread::Semaphore;
562
563           sub thr_func
564           {
565               my $sema = shift;
566
567               # Thread 'suspend/resume' signal handler
568               $SIG{'STOP'} = sub {
569                   $sema->down();      # Thread suspended
570                   $sema->up();        # Thread resumes
571               };
572
573               ...
574           }
575
576           # Create a semaphore and pass it to a thread
577           my $sema = Thread::Semaphore->new();
578           my $thr = threads->create('thr_func', $sema);
579
580           # Suspend the thread
581           $sema->down();
582           $thr->kill('STOP');
583
584           ...
585
586           # Allow the thread to continue
587           $sema->up();
588
589       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
596       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
600       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
607       Sending a signal to a terminated thread is ignored.
608

WARNINGS

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
614           NOTE:  If the main thread exits, then this warning cannot be
615           suppressed using "no warnings 'threads';" as suggested below.
616
617       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
621       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
627       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
632       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
636       If needed, thread warnings can be suppressed by using:
637
638           no warnings 'threads';
639
640       in the appropriate scope.
641

ERRORS

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
647           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
652       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
656               $thr->set_stack_size($size);
657
658       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
662       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

BUGS AND LIMITATIONS

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
671       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
676       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
683           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
687               sub thr_func
688               {
689                   require Unsafe::Module
690                   # Unsafe::Module->import(...);
691
692                   ....
693               }
694
695           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
700           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
704       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
715       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
721           On MSWin32, each thread maintains its own the current working
722           directory setting.
723
724       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
731           To work around this, set environment variables as part of the
732           system call.  For example:
733
734               my $msg = 'hello';
735               system("FOO=$msg; echo \$FOO");   # Outputs 'hello' to STDOUT
736
737           On MSWin32, each thread maintains its own set of environment
738           variables.
739
740       Parent-child threads
741           On some platforms, it might not be possible to destroy parent
742           threads while there are still existing child threads.
743
744       Creating threads inside special blocks
745           Creating threads inside "BEGIN", "CHECK" or "INIT" blocks should
746           not be relied upon.  Depending on the Perl version and the
747           application code, results may range from success, to (apparently
748           harmless) warnings of leaked scalar, or all the way up to crashing
749           of the Perl interpreter.
750
751       Unsafe signals
752           Since Perl 5.8.0, signals have been made safer in Perl by
753           postponing their handling until the interpreter is in a safe state.
754           See "Safe Signals" in perl58delta and "Deferred Signals (Safe
755           Signals)" in perlipc for more details.
756
757           Safe signals is the default behavior, and the old, immediate,
758           unsafe signalling behavior is only in effect in the following
759           situations:
760
761           ·   Perl has been built with "PERL_OLD_SIGNALS" (see "perl -V").
762
763           ·   The environment variable "PERL_SIGNALS" is set to "unsafe" (see
764               "PERL_SIGNALS" in perlrun).
765
766           ·   The module Perl::Unsafe::Signals is used.
767
768           If unsafe signals is in effect, then signal handling is not thread-
769           safe, and the "->kill()" signalling method cannot be used.
770
771       Returning closures from threads
772           Returning closures from threads should not be relied upon.
773           Depending of the Perl version and the application code, results may
774           range from success, to (apparently harmless) warnings of leaked
775           scalar, or all the way up to crashing of the Perl interpreter.
776
777       Returning objects from threads
778           Returning objects from threads does not work.  Depending on the
779           classes involved, you may be able to work around this by returning
780           a serialized version of the object (e.g., using Data::Dumper or
781           Storable), and then reconstituting it in the joining thread.  If
782           you're using Perl 5.10.0 or later, and if the class supports shared
783           objects, you can pass them via shared queues.
784
785       END blocks in threads
786           It is possible to add END blocks to threads by using require or
787           eval with the appropriate code.  These "END" blocks will then be
788           executed when the thread's interpreter is destroyed (i.e., either
789           during a "->join()" call, or at program termination).
790
791           However, calling any threads methods in such an "END" block will
792           most likely fail (e.g., the application may hang, or generate an
793           error) due to mutexes that are needed to control functionality
794           within the threads module.
795
796           For this reason, the use of "END" blocks in threads is strongly
797           discouraged.
798
799       Open directory handles
800           In perl 5.14 and higher, on systems other than Windows that do not
801           support the "fchdir" C function, directory handles (see opendir)
802           will not be copied to new threads. You can use the "d_fchdir"
803           variable in Config.pm to determine whether your system supports it.
804
805           In prior perl versions, spawning threads with open directory
806           handles would crash the interpreter.  <[perl #75154]>
807
808       Perl Bugs and the CPAN Version of threads
809           Support for threads extends beyond the code in this module (i.e.,
810           threads.pm and threads.xs), and into the Perl interpreter itself.
811           Older versions of Perl contain bugs that may manifest themselves
812           despite using the latest version of threads from CPAN.  There is no
813           workaround for this other than upgrading to the latest version of
814           Perl.
815
816           Even with the latest version of Perl, it is known that certain
817           constructs with threads may result in warning messages concerning
818           leaked scalars or unreferenced scalars.  However, such warnings are
819           harmless, and may safely be ignored.
820
821           You can search for threads related bug reports at
822           <http://rt.cpan.org/Public/>.  If needed submit any new bugs,
823           problems, patches, etc. to:
824           <http://rt.cpan.org/Public/Dist/Display.html?Name=threads>
825

REQUIREMENTS

827       Perl 5.8.0 or later
828

SEE ALSO

830       threads Discussion Forum on CPAN:
831       <http://www.cpanforum.com/dist/threads>
832
833       threads::shared, perlthrtut
834
835       <http://www.perl.com/pub/a/2002/06/11/threads.html> and
836       <http://www.perl.com/pub/a/2002/09/04/threads.html>
837
838       Perl threads mailing list:
839       <http://lists.cpan.org/showlist.cgi?name=iThreads>
840
841       Stack size discussion: <http://www.perlmonks.org/?node_id=532956>
842

AUTHOR

844       Artur Bergman <sky AT crucially DOT net>
845
846       CPAN version produced by Jerry D. Hedden <jdhedden AT cpan DOT org>
847

LICENSE

849       threads is released under the same license as Perl.
850

ACKNOWLEDGEMENTS

852       Richard Soderberg <perl AT crystalflame DOT net> - Helping me out tons,
853       trying to find reasons for races and other weird bugs!
854
855       Simon Cozens <simon AT brecon DOT co DOT uk> - Being there to answer
856       zillions of annoying questions
857
858       Rocco Caputo <troc AT netrus DOT net>
859
860       Vipul Ved Prakash <mail AT vipul DOT net> - Helping with debugging
861
862       Dean Arnold <darnold AT presicient DOT com> - Stack size API
863
864
865
866perl v5.10.1                      2017-03-22                      threads(3pm)
Impressum