This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade to Devel::PPPort 3.08_07
[perl5.git] / ext / threads / threads.pm
CommitLineData
47ba8780
AB
1package threads;
2
32419a4c 3use 5.008;
fcea4b7c 4
47ba8780
AB
5use strict;
6use warnings;
73e09c8f 7
58a3a76c 8our $VERSION = '1.32';
fcea4b7c
JH
9my $XS_VERSION = $VERSION;
10$VERSION = eval $VERSION;
73e09c8f 11
73e09c8f 12
fcea4b7c
JH
13BEGIN {
14 # Verify this Perl supports threads
15 use Config;
16 if (! $Config{useithreads}) {
17 die("This Perl not built to support threads\n");
73e09c8f 18 }
47ba8780 19
fcea4b7c
JH
20 # Declare that we have been loaded
21 $threads::threads = 1;
22
23 # Complain if 'threads' is loaded after 'threads::shared'
24 if ($threads::shared::threads_shared) {
25 warn <<'_MSG_';
26Warning, threads::shared has already been loaded. To
27enable shared variables, 'use threads' must be called
28before threads::shared or any module that uses it.
29_MSG_
30 }
dab065ea
AB
31}
32
fc04eb16 33
0f1612a7
JH
34# Load the XS code
35require XSLoader;
fcea4b7c 36XSLoader::load('threads', $XS_VERSION);
47ba8780 37
47ba8780 38
0f1612a7 39### Export ###
47ba8780 40
0f1612a7
JH
41sub import
42{
43 my $class = shift; # Not used
44
45 # Exported subroutines
46 my @EXPORT = qw(async);
47
48 # Handle args
49 while (my $sym = shift) {
514612b7
JH
50 if ($sym =~ /^stack/) {
51 threads->set_stack_size(shift);
52
53 } elsif ($sym =~ /all/) {
0f1612a7
JH
54 push(@EXPORT, qw(yield));
55
56 } else {
57 push(@EXPORT, $sym);
58 }
59 }
60
61 # Export subroutine names
62 my $caller = caller();
63 foreach my $sym (@EXPORT) {
64 no strict 'refs';
65 *{$caller.'::'.$sym} = \&{$sym};
66 }
514612b7
JH
67
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'});
71 }
0f1612a7
JH
72}
73
74
75### Methods, etc. ###
47ba8780 76
f4cc38af
JH
77# 'new' is an alias for 'create'
78*new = \&create;
68795e93 79
fcea4b7c
JH
80# 'async' is a function alias for the 'threads->create()' method
81sub async (&;@)
82{
83 unshift(@_, 'threads');
84 # Use "goto" trick to avoid pad problems from 5.8.1 (fixed in 5.8.2)
85 goto &create;
86}
87
88# Thread object equality checking
89use overload (
90 '==' => \&equal,
91 '!=' => sub { ! equal(@_) },
92 'fallback' => 1
93);
94
47ba8780 951;
0f1612a7 96
47ba8780
AB
97__END__
98
99=head1 NAME
100
0f1612a7
JH
101threads - Perl interpreter-based threads
102
103=head1 VERSION
104
58a3a76c 105This document describes threads version 1.32
47ba8780
AB
106
107=head1 SYNOPSIS
108
514612b7 109 use threads ('yield', 'stack_size' => 64*4096);
47ba8780 110
38875929 111 sub start_thread {
0f1612a7 112 my @args = @_;
9d9ff5b1 113 print('Thread started: ', join(' ', @args), "\n");
38875929 114 }
0f1612a7
JH
115 my $thread = threads->create('start_thread', 'argument');
116 $thread->join();
117
118 threads->create(sub { print("I am a thread\n"); })->join();
47ba8780 119
38875929 120 my $thread3 = async { foreach (@files) { ... } };
0f1612a7
JH
121 $thread3->join();
122
9d9ff5b1 123 # Invoke thread in list context (implicit) so it can return a list
0f1612a7 124 my ($thr) = threads->create(sub { return (qw/a b c/); });
9d9ff5b1
JH
125 # or specify list context explicitly
126 my $thr = threads->create({'context' => 'list'},
127 sub { return (qw/a b c/); });
0f1612a7 128 my @results = $thr->join();
47ba8780 129
38875929 130 $thread->detach();
47ba8780 131
38875929 132 $thread = threads->self();
0f1612a7 133 $thread = threads->object($tid);
11c51ed3 134
0f1612a7
JH
135 $tid = threads->tid();
136 $tid = threads->self->tid();
137 $tid = $thread->tid();
47ba8780 138
38875929 139 threads->yield();
0f1612a7
JH
140 yield();
141
142 my @threads = threads->list();
fcea4b7c 143 my $thread_count = threads->list();
f9dff5f5 144
0f1612a7
JH
145 if ($thr1 == $thr2) {
146 ...
147 }
678a9b6c 148
514612b7
JH
149 $stack_size = threads->get_stack_size();
150 $old_size = threads->set_stack_size(32*4096);
151
9d9ff5b1
JH
152 # Create a thread with a specific context and stack size
153 my $thr = threads->create({ 'context' => 'list',
154 'stack_size' => 32*4096 },
155 \&foo);
156 my @results = $thr->join();
157
c0003851
JH
158 $thr->kill('SIGUSR1');
159
47ba8780
AB
160=head1 DESCRIPTION
161
fc04eb16
JH
162Perl 5.6 introduced something called interpreter threads. Interpreter threads
163are different from I<5005threads> (the thread model of Perl 5.005) by creating
164a new Perl interpreter per thread, and not sharing any data or state between
165threads by default.
11c51ed3 166
fc04eb16
JH
167Prior to Perl 5.8, this has only been available to people embedding Perl, and
168for emulating fork() on Windows.
11c51ed3 169
fc04eb16
JH
170The I<threads> API is loosely based on the old Thread.pm API. It is very
171important to note that variables are not shared between threads, all variables
172are by default thread local. To use shared variables one must use
173L<threads::shared>.
11c51ed3 174
fc04eb16
JH
175It is also important to note that you must enable threads by doing C<use
176threads> as early as possible in the script itself, and that it is not
177possible to enable threading inside an C<eval "">, C<do>, C<require>, or
178C<use>. In particular, if you are intending to share variables with
179L<threads::shared>, you must C<use threads> before you C<use threads::shared>.
180(C<threads> will emit a warning if you do it the other way around.)
47ba8780
AB
181
182=over
183
0f1612a7 184=item $thr = threads->create(FUNCTION, ARGS)
47ba8780 185
0f1612a7
JH
186This will create a new thread that will begin execution with the specified
187entry point function, and give it the I<ARGS> list as parameters. It will
188return the corresponding threads object, or C<undef> if thread creation failed.
47ba8780 189
0f1612a7
JH
190I<FUNCTION> may either be the name of a function, an anonymous subroutine, or
191a code ref.
47ba8780 192
0f1612a7
JH
193 my $thr = threads->create('func_name', ...);
194 # or
195 my $thr = threads->create(sub { ... }, ...);
196 # or
197 my $thr = threads->create(\&func, ...);
93512b4d 198
0f1612a7
JH
199The C<-E<gt>new()> method is an alias for C<-E<gt>create()>.
200
201=item $thr->join()
202
203This will wait for the corresponding thread to complete its execution. When
204the thread finishes, C<-E<gt>join()> will return the return value(s) of the
205entry point function.
206
9d9ff5b1
JH
207The context (void, scalar or list) for the return value(s) for C<-E<gt>join()>
208is determined at the time of thread creation.
0f1612a7 209
9d9ff5b1 210 # Create thread in list context (implicit)
0f1612a7
JH
211 my ($thr1) = threads->create(sub {
212 my @results = qw(a b c);
213 return (@results);
9d9ff5b1
JH
214 });
215 # or (explicit)
216 my $thr1 = threads->create({'context' => 'list'},
217 sub {
218 my @results = qw(a b c);
219 return (@results);
220 });
0f1612a7
JH
221 # Retrieve list results from thread
222 my @res1 = $thr1->join();
223
9d9ff5b1 224 # Create thread in scalar context (implicit)
0f1612a7
JH
225 my $thr2 = threads->create(sub {
226 my $result = 42;
227 return ($result);
9d9ff5b1 228 });
0f1612a7
JH
229 # Retrieve scalar result from thread
230 my $res2 = $thr2->join();
231
9d9ff5b1
JH
232 # Create a thread in void context (explicit)
233 my $thr3 = threads->create({'void' => 1},
234 sub { print("Hello, world\n"); });
235 # Join the thread in void context (i.e., no return value)
236 $thr3->join();
237
238See L</"THREAD CONTEXT"> for more details.
239
0f1612a7
JH
240If the program exits without all other threads having been either joined or
241detached, then a warning will be issued. (A program exits either because one
242of its threads explicitly calls L<exit()|perlfunc/"exit EXPR">, or in the case
243of the main thread, reaches the end of the main program file.)
93512b4d 244
fcea4b7c
JH
245Calling C<-E<gt>join()> or C<-E<gt>detach()> on an already joined thread will
246cause an error to be thrown.
47ba8780 247
fcea4b7c 248=item $thr->detach()
47ba8780 249
fcea4b7c
JH
250Makes the thread unjoinable, and causes any eventual return value to be
251discarded.
252
253Calling C<-E<gt>join()> or C<-E<gt>detach()> on an already detached thread
254will cause an error to be thrown.
0f1612a7
JH
255
256=item threads->detach()
257
258Class method that allows a thread to detach itself.
259
fcea4b7c 260=item threads->self()
47ba8780 261
fcea4b7c 262Class method that allows a thread to obtain its own I<threads> object.
47ba8780 263
0f1612a7
JH
264=item $thr->tid()
265
266Returns the ID of the thread. Thread IDs are unique integers with the main
267thread in a program being 0, and incrementing by 1 for every thread created.
47ba8780 268
0f1612a7 269=item threads->tid()
38875929 270
0f1612a7 271Class method that allows a thread to obtain its own ID.
47ba8780 272
0f1612a7 273=item threads->object($tid)
8c9849ff 274
0f1612a7
JH
275This will return the I<threads> object for the I<active> thread associated
276with the specified thread ID. Returns C<undef> if there is no thread
277associated with the TID, if the thread is joined or detached, if no TID is
278specified or if the specified TID is undef.
8c9849ff 279
fcea4b7c 280=item threads->yield()
f9dff5f5 281
38875929
DM
282This is a suggestion to the OS to let this thread yield CPU time to other
283threads. What actually happens is highly dependent upon the underlying
284thread implementation.
f9dff5f5 285
fcea4b7c 286You may do C<use threads qw(yield)>, and then just use C<yield()> in your
70f2e746
DM
287code.
288
f4cc38af 289=item threads->list()
678a9b6c 290
f4cc38af
JH
291In a list context, returns a list of all non-joined, non-detached I<threads>
292objects. In a scalar context, returns a count of the same.
678a9b6c 293
0f1612a7
JH
294=item $thr1->equal($thr2)
295
296Tests if two threads objects are the same thread or not. This is overloaded
fcea4b7c 297to the more natural forms:
0f1612a7
JH
298
299 if ($thr1 == $thr2) {
300 print("Threads are the same\n");
301 }
fcea4b7c
JH
302 # or
303 if ($thr1 != $thr2) {
304 print("Threads differ\n");
305 }
0f1612a7
JH
306
307(Thread comparison is based on thread IDs.)
308
386c44e5
AB
309=item async BLOCK;
310
311C<async> creates a thread to execute the block immediately following
fcea4b7c
JH
312it. This block is treated as an anonymous subroutine, and so must have a
313semi-colon after the closing brace. Like C<threads->create()>, C<async>
314returns a I<threads> object.
386c44e5 315
f4cc38af
JH
316=item $thr->_handle()
317
318This I<private> method returns the memory location of the internal thread
fcea4b7c
JH
319structure associated with a threads object. For Win32, this is a pointer to
320the C<HANDLE> value returned by C<CreateThread> (i.e., C<HANDLE *>); for other
321platforms, it is a pointer to the C<pthread_t> structure used in the
404aaa48 322C<pthread_create> call (i.e., C<pthread_t *>).
f4cc38af
JH
323
324This method is of no use for general Perl threads programming. Its intent is
325to provide other (XS-based) thread modules with the capability to access, and
326possibly manipulate, the underlying thread structure associated with a Perl
327thread.
328
329=item threads->_handle()
330
331Class method that allows a thread to obtain its own I<handle>.
332
47ba8780
AB
333=back
334
9d9ff5b1
JH
335=head1 THREAD CONTEXT
336
337As with subroutines, the type of value returned from a thread's entry point
338function may be determined by the thread's I<context>: list, scalar or void.
339The thread's context is determined at thread creation. This is necessary so
340that the context is available to the entry point function via
206f4df7 341L<wantarray()|perlfunc/"wantarray">. The thread may then specify a value of
9d9ff5b1
JH
342the appropriate type to be returned from C<-E<gt>join()>.
343
344=head2 Explicit context
345
346Because thread creation and thread joining may occur in different contexts, it
347may be desirable to state the context explicitly to the thread's entry point
348function. This may be done by calling C<-E<gt>create()> with a parameter hash
349as the first argument:
350
351 my $thr = threads->create({'context' => 'list'}, \&foo);
352 ...
353 my @results = $thr->join();
354
355In the above, the threads object is returned to the parent thread in scalar
356context, and the thread's entry point function C<foo> will be called in list
357context such that the parent thread can receive a list from the C<-E<gt>join()>
358call. Similarly, if you need the threads object, but your thread will not be
359returning a value (i.e., I<void> context), you would do the following:
360
361 my $thr = threads->create({'context' => 'void'}, \&foo);
362 ...
363 $thr->join();
364
365The context type may also be used as the I<key> in the parameter hash followed
366by a I<true> value:
367
368 threads->create({'scalar' => 1}, \&foo);
369 ...
370 my ($thr) = threads->list();
371 my $result = $thr->join();
372
373=head2 Implicit context
374
375If not explicitly stated, the thread's context is implied from the context
376of the C<-E<gt>create()> call:
377
378 # Create thread in list context
379 my ($thr) = threads->create(...);
380
381 # Create thread in scalar context
382 my $thr = threads->create(...);
383
384 # Create thread in void context
385 threads->create(...);
386
514612b7
JH
387=head1 THREAD STACK SIZE
388
389The default per-thread stack size for different platforms varies
390significantly, and is almost always far more than is needed for most
391applications. On Win32, Perl's makefile explicitly sets the default stack to
39216 MB; on most other platforms, the system default is used, which again may be
393much larger than is needed.
394
395By tuning the stack size to more accurately reflect your application's needs,
396you may significantly reduce your application's memory usage, and increase the
397number of simultaneously running threads.
398
399N.B., on Windows, Address space allocation granularity is 64 KB, therefore,
400setting the stack smaller than that on Win32 Perl will not save any more
401memory.
402
403=over
404
405=item threads->get_stack_size();
406
407Returns the current default per-thread stack size. The default is zero, which
408means the system default stack size is currently in use.
409
410=item $size = $thr->get_stack_size();
411
412Returns the stack size for a particular thread. A return value of zero
413indicates the system default stack size was used for the thread.
414
415=item $old_size = threads->set_stack_size($new_size);
416
417Sets a new default per-thread stack size, and returns the previous setting.
418
419Some platforms have a minimum thread stack size. Trying to set the stack size
420below this value will result in a warning, and the minimum stack size will be
421used.
422
423Some Linux platforms have a maximum stack size. Setting too large of a stack
424size will cause thread creation to fail.
425
426If needed, C<$new_size> will be rounded up to the next multiple of the memory
427page size (usually 4096 or 8192).
428
429Threads created after the stack size is set will then either call
430C<pthread_attr_setstacksize()> I<(for pthreads platforms)>, or supply the
431stack size to C<CreateThread()> I<(for Win32 Perl)>.
432
433(Obviously, this call does not affect any currently extant threads.)
434
435=item use threads ('stack_size' => VALUE);
436
437This sets the default per-thread stack size at the start of the application.
438
439=item $ENV{'PERL5_ITHREADS_STACK_SIZE'}
440
441The default per-thread stack size may be set at the start of the application
442through the use of the environment variable C<PERL5_ITHREADS_STACK_SIZE>:
443
444 PERL5_ITHREADS_STACK_SIZE=1048576
445 export PERL5_ITHREADS_STACK_SIZE
446 perl -e'use threads; print(threads->get_stack_size(), "\n")'
447
448This value overrides any C<stack_size> parameter given to C<use threads>. Its
449primary purpose is to permit setting the per-thread stack size for legacy
450threaded applications.
451
452=item threads->create({'stack_size' => VALUE}, FUNCTION, ARGS)
453
9d9ff5b1
JH
454The stack size an individual threads may also be specified. This may be done
455by calling C<-E<gt>create()> with a parameter hash as the first argument:
456
457 my $thr = threads->create({'stack_size' => 32*4096}, \&foo, @args);
514612b7
JH
458
459=item $thr2 = $thr1->create(FUNCTION, ARGS)
460
461This creates a new thread (C<$thr2>) that inherits the stack size from an
462existing thread (C<$thr1>). This is shorthand for the following:
463
464 my $stack_size = $thr1->get_stack_size();
465 my $thr2 = threads->create({'stack_size' => $stack_size}, FUNCTION, ARGS);
466
467=back
468
c0003851
JH
469=head1 THREAD SIGNALLING
470
9d9ff5b1 471When safe signals is in effect (the default behavior - see L</"Unsafe signals">
1152d448
JH
472for more details), then signals may be sent and acted upon by individual
473threads.
c0003851
JH
474
475=over 4
476
477=item $thr->kill('SIG...');
478
479Sends the specified signal to the thread. Signal names and (positive) signal
480numbers are the same as those supported by
481L<kill()|perlfunc/"kill SIGNAL, LIST">. For example, 'SIGTERM', 'TERM' and
482(depending on the OS) 15 are all valid arguments to C<-E<gt>kill()>.
483
484Returns the thread object to allow for method chaining:
485
486 $thr->kill('SIG...')->join();
487
488=back
489
490Signal handlers need to be set up in the threads for the signals they are
491expected to act upon. Here's an example for I<cancelling> a thread:
492
493 use threads;
494
495 # Suppress warning message when thread is 'killed'
496 no warnings 'threads';
497
498 sub thr_func
499 {
500 # Thread 'cancellation' signal handler
501 $SIG{'KILL'} = sub { die("Thread killed\n"); };
502
503 ...
504 }
505
506 # Create a thread
507 my $thr = threads->create('thr_func');
508
509 ...
510
511 # Signal the thread to terminate, and then detach
512 # it so that it will get cleaned up automatically
513 $thr->kill('KILL')->detach();
514
404aaa48
JH
515Here's another simplistic example that illustrates the use of thread
516signalling in conjunction with a semaphore to provide rudimentary I<suspend>
517and I<resume> capabilities:
c0003851
JH
518
519 use threads;
520 use Thread::Semaphore;
521
522 sub thr_func
523 {
524 my $sema = shift;
525
526 # Thread 'suspend/resume' signal handler
527 $SIG{'STOP'} = sub {
528 $sema->down(); # Thread suspended
529 $sema->up(); # Thread resumes
530 };
531
532 ...
533 }
534
535 # Create a semaphore and send it to a thread
536 my $sema = Thread::Semaphore->new();
537 my $thr = threads->create('thr_func', $sema);
538
539 # Suspend the thread
540 $sema->down();
541 $thr->kill('STOP');
542
543 ...
544
545 # Allow the thread to continue
546 $sema->up();
547
404aaa48
JH
548CAVEAT: The thread signalling capability provided by this module does not
549actually send signals via the OS. It I<emulates> signals at the Perl-level
550such that signal handlers are called in the appropriate thread. For example,
551sending C<$thr-E<gt>kill('STOP')> does not actually suspend a thread (or the
552whole process), but does cause a C<$SIG{'STOP'}> handler to be called in that
553thread (as illustrated above).
554
555As such, signals that would normally not be appropriate to use in the
556C<kill()> command (e.g., C<kill('KILL', $$)>) are okay to use with the
557C<-E<gt>kill()> method (again, as illustrated above).
558
559Correspondingly, sending a signal to a thread does not disrupt the operation
560the thread is currently working on: The signal will be acted upon after the
c0003851
JH
561current operation has completed. For instance, if the thread is I<stuck> on
562an I/O call, sending it a signal will not cause the I/O call to be interrupted
563such that the signal is acted up immediately.
564
e4f9f4fe
JH
565=head1 WARNINGS
566
567=over 4
568
fcea4b7c 569=item A thread exited while # other threads were still running
e4f9f4fe 570
fc04eb16
JH
571A thread (not necessarily the main thread) exited while there were still other
572threads running. Usually, it's a good idea to first collect the return values
573of the created threads by joining them, and only then exit from the main
574thread.
e4f9f4fe 575
c0003851
JH
576=item Thread creation failed: pthread_create returned #
577
578See the appropriate I<man> page for C<pthread_create> to determine the actual
579cause for the failure.
580
581=item Thread # terminated abnormally: ...
582
583A thread terminated in some manner other than just returning from its entry
584point function. For example, the thread may have exited via C<die>.
585
514612b7
JH
586=item Using minimum thread stack size of #
587
588Some platforms have a minimum thread stack size. Trying to set the stack size
589below this value will result in the above warning, and the stack size will be
590set to the minimum.
591
c0003851
JH
592=item Thread creation failed: pthread_attr_setstacksize(I<SIZE>) returned 22
593
594The specified I<SIZE> exceeds the system's maximum stack size. Use a smaller
595value for the stack size.
596
e4f9f4fe 597=back
47ba8780 598
c0003851
JH
599If needed, thread warnings can be suppressed by using:
600
601 no warnings 'threads';
602
603in the appropriate scope.
604
0f1612a7
JH
605=head1 ERRORS
606
607=over 4
608
fcea4b7c 609=item This Perl not built to support threads
678a9b6c 610
0f1612a7
JH
611The particular copy of Perl that you're trying to use was not built using the
612C<useithreads> configuration option.
678a9b6c 613
0f1612a7
JH
614Having threads support requires all of Perl and all of the XS modules in the
615Perl installation to be rebuilt; it is not just a question of adding the
616L<threads> module (i.e., threaded and non-threaded Perls are binary
617incompatible.)
618
514612b7
JH
619=item Cannot change stack size of an existing thread
620
621The stack size of currently extant threads cannot be changed, therefore, the
622following results in the above error:
623
624 $thr->set_stack_size($size);
625
c0003851 626=item Cannot signal other threads without safe signals
514612b7 627
1152d448 628Safe signals must be in effect to use the C<-E<gt>kill()> signalling method.
9d9ff5b1 629See L</"Unsafe signals"> for more details.
c0003851
JH
630
631=item Unrecognized signal name: ...
632
633The particular copy of Perl that you're trying to use does not support the
634specified signal being used in a C<-E<gt>kill()> call.
514612b7 635
0f1612a7 636=back
47ba8780 637
ab80e3f2
EM
638=head1 BUGS
639
47ba8780
AB
640=over
641
fcea4b7c 642=item Parent-child threads
678a9b6c 643
fcea4b7c
JH
644On some platforms, it might not be possible to destroy I<parent> threads while
645there are still existing I<child> threads.
678a9b6c 646
404aaa48 647=item Creating threads inside special blocks
88f8c1df 648
f2e0bb91
JH
649Creating threads inside C<BEGIN>, C<CHECK> or C<INIT> blocks should not be
650relied upon. Depending on the Perl version and the application code, results
58a3a76c 651may range from success, to (apparently harmless) warnings of leaked scalar, or
f2e0bb91 652all the way up to crashing of the Perl interpreter.
88f8c1df 653
1152d448 654=item Unsafe signals
47ba8780 655
1152d448
JH
656Since Perl 5.8.0, signals have been made safer in Perl by postponing their
657handling until the interpreter is in a I<safe> state. See
404aaa48 658L<perl58delta/"Safe Signals"> and L<perlipc/"Deferred Signals (Safe Signals)">
1152d448
JH
659for more details.
660
661Safe signals is the default behavior, and the old, immediate, unsafe
662signalling behavior is only in effect in the following situations:
663
664=over 4
665
666=item * Perl was been built with C<PERL_OLD_SIGNALS> (see C<perl -V>).
667
668=item * The environment variable C<PERL_SIGNALS> is set to C<unsafe> (see L<perlrun/"PERL_SIGNALS">).
669
670=item * The module L<Perl::Unsafe::Signals> is used.
671
672=back
673
674If unsafe signals is in effect, then signal handling is not thread-safe, and
675the C<-E<gt>kill()> signalling method cannot be used.
88f8c1df 676
0f1612a7
JH
677=item Returning closures from threads
678
f2e0bb91
JH
679Returning closures from threads should not be relied upon. Depending of the
680Perl version and the application code, results may range from success, to
58a3a76c
JH
681(apparently harmless) warnings of leaked scalar, or all the way up to crashing
682of the Perl interpreter.
0f1612a7
JH
683
684=item Perl Bugs and the CPAN Version of L<threads>
685
686Support for threads extents beyond the code in this module (i.e.,
687F<threads.pm> and F<threads.xs>), and into the Perl iterpreter itself. Older
688versions of Perl contain bugs that may manifest themselves despite using the
689latest version of L<threads> from CPAN. There is no workaround for this other
690than upgrading to the lastest version of Perl.
691
692(Before you consider posting a bug report, please consult, and possibly post a
693message to the discussion forum to see if what you've encountered is a known
694problem.)
695
47ba8780
AB
696=back
697
0f1612a7 698=head1 REQUIREMENTS
47ba8780 699
0f1612a7 700Perl 5.8.0 or later
47ba8780 701
0f1612a7 702=head1 SEE ALSO
47ba8780 703
0f1612a7
JH
704L<threads> Discussion Forum on CPAN:
705L<http://www.cpanforum.com/dist/threads>
47ba8780 706
0f1612a7 707Annotated POD for L<threads>:
58a3a76c 708L<http://annocpan.org/~JDHEDDEN/threads-1.32/shared.pm>
47ba8780 709
0f1612a7 710L<threads::shared>, L<perlthrtut>
47ba8780 711
0f1612a7
JH
712L<http://www.perl.com/pub/a/2002/06/11/threads.html> and
713L<http://www.perl.com/pub/a/2002/09/04/threads.html>
47ba8780 714
0f1612a7
JH
715Perl threads mailing list:
716L<http://lists.cpan.org/showlist.cgi?name=iThreads>
47ba8780 717
514612b7
JH
718Stack size discussion:
719L<http://www.perlmonks.org/?node_id=532956>
720
0f1612a7 721=head1 AUTHOR
47ba8780 722
0f1612a7
JH
723Artur Bergman E<lt>sky AT crucially DOT netE<gt>
724
725threads is released under the same license as Perl.
726
727CPAN version produced by Jerry D. Hedden <jdhedden AT cpan DOT org>
728
729=head1 ACKNOWLEDGEMENTS
730
731Richard Soderberg E<lt>perl AT crystalflame DOT netE<gt> -
732Helping me out tons, trying to find reasons for races and other weird bugs!
733
734Simon Cozens E<lt>simon AT brecon DOT co DOT ukE<gt> -
735Being there to answer zillions of annoying questions
736
737Rocco Caputo E<lt>troc AT netrus DOT netE<gt>
47ba8780 738
0f1612a7
JH
739Vipul Ved Prakash E<lt>mail AT vipul DOT netE<gt> -
740Helping with debugging
47ba8780 741
514612b7
JH
742Dean Arnold E<lt>darnold AT presicient DOT comE<gt> -
743Stack size API
744
47ba8780 745=cut