Commit | Line | Data |
---|---|---|
47ba8780 AB |
1 | package threads; |
2 | ||
32419a4c | 3 | use 5.008; |
fcea4b7c | 4 | |
47ba8780 AB |
5 | use strict; |
6 | use warnings; | |
73e09c8f | 7 | |
9fadc397 | 8 | our $VERSION = '1.94'; |
fcea4b7c JH |
9 | my $XS_VERSION = $VERSION; |
10 | $VERSION = eval $VERSION; | |
73e09c8f | 11 | |
c527c90b JH |
12 | # Verify this Perl supports threads |
13 | require Config; | |
14 | if (! $Config::Config{useithreads}) { | |
15 | die("This Perl not built to support threads\n"); | |
16 | } | |
73e09c8f | 17 | |
c527c90b JH |
18 | # Complain if 'threads' is loaded after 'threads::shared' |
19 | if ($threads::shared::threads_shared) { | |
20 | warn <<'_MSG_'; | |
fcea4b7c JH |
21 | Warning, threads::shared has already been loaded. To |
22 | enable shared variables, 'use threads' must be called | |
23 | before threads::shared or any module that uses it. | |
24 | _MSG_ | |
dab065ea AB |
25 | } |
26 | ||
45cd5be7 SP |
27 | # Declare that we have been loaded |
28 | $threads::threads = 1; | |
29 | ||
0f1612a7 JH |
30 | # Load the XS code |
31 | require XSLoader; | |
fcea4b7c | 32 | XSLoader::load('threads', $XS_VERSION); |
47ba8780 | 33 | |
47ba8780 | 34 | |
0f1612a7 | 35 | ### Export ### |
47ba8780 | 36 | |
0f1612a7 JH |
37 | sub import |
38 | { | |
39 | my $class = shift; # Not used | |
40 | ||
41 | # Exported subroutines | |
42 | my @EXPORT = qw(async); | |
43 | ||
44 | # Handle args | |
45 | while (my $sym = shift) { | |
6ebc233e RGS |
46 | if ($sym =~ /^(?:stack|exit)/i) { |
47 | if (defined(my $arg = shift)) { | |
48 | if ($sym =~ /^stack/i) { | |
49 | threads->set_stack_size($arg); | |
50 | } else { | |
51 | $threads::thread_exit_only = $arg =~ /^thread/i; | |
52 | } | |
53 | } else { | |
54 | require Carp; | |
55 | Carp::croak("threads: Missing argument for option: $sym"); | |
56 | } | |
69a9b4b8 | 57 | |
3ab14376 JH |
58 | } elsif ($sym =~ /^str/i) { |
59 | import overload ('""' => \&tid); | |
60 | ||
18b9e6f5 | 61 | } elsif ($sym =~ /^(?::all|yield)$/) { |
0f1612a7 JH |
62 | push(@EXPORT, qw(yield)); |
63 | ||
64 | } else { | |
de42e62a JH |
65 | require Carp; |
66 | Carp::croak("threads: Unknown import option: $sym"); | |
0f1612a7 JH |
67 | } |
68 | } | |
69 | ||
70 | # Export subroutine names | |
71 | my $caller = caller(); | |
72 | foreach my $sym (@EXPORT) { | |
73 | no strict 'refs'; | |
74 | *{$caller.'::'.$sym} = \&{$sym}; | |
75 | } | |
514612b7 JH |
76 | |
77 | # Set stack size via environment variable | |
78 | if (exists($ENV{'PERL5_ITHREADS_STACK_SIZE'})) { | |
79 | threads->set_stack_size($ENV{'PERL5_ITHREADS_STACK_SIZE'}); | |
80 | } | |
0f1612a7 JH |
81 | } |
82 | ||
83 | ||
84 | ### Methods, etc. ### | |
47ba8780 | 85 | |
69a9b4b8 | 86 | # Exit from a thread (only) |
4dcb9e53 JH |
87 | sub exit |
88 | { | |
69a9b4b8 RGS |
89 | my ($class, $status) = @_; |
90 | if (! defined($status)) { | |
91 | $status = 0; | |
92 | } | |
93 | ||
94 | # Class method only | |
95 | if (ref($class)) { | |
96 | require Carp; | |
da140a40 | 97 | Carp::croak('Usage: threads->exit(status)'); |
69a9b4b8 RGS |
98 | } |
99 | ||
100 | $class->set_thread_exit_only(1); | |
101 | CORE::exit($status); | |
4dcb9e53 JH |
102 | } |
103 | ||
ead32952 JH |
104 | # 'Constant' args for threads->list() |
105 | sub threads::all { } | |
106 | sub threads::running { 1 } | |
107 | sub threads::joinable { 0 } | |
108 | ||
f4cc38af JH |
109 | # 'new' is an alias for 'create' |
110 | *new = \&create; | |
68795e93 | 111 | |
fcea4b7c JH |
112 | # 'async' is a function alias for the 'threads->create()' method |
113 | sub async (&;@) | |
114 | { | |
115 | unshift(@_, 'threads'); | |
116 | # Use "goto" trick to avoid pad problems from 5.8.1 (fixed in 5.8.2) | |
117 | goto &create; | |
118 | } | |
119 | ||
120 | # Thread object equality checking | |
121 | use overload ( | |
122 | '==' => \&equal, | |
123 | '!=' => sub { ! equal(@_) }, | |
124 | 'fallback' => 1 | |
125 | ); | |
126 | ||
47ba8780 | 127 | 1; |
0f1612a7 | 128 | |
47ba8780 AB |
129 | __END__ |
130 | ||
131 | =head1 NAME | |
132 | ||
0f1612a7 JH |
133 | threads - Perl interpreter-based threads |
134 | ||
135 | =head1 VERSION | |
136 | ||
0ecf2317 | 137 | This document describes threads version 1.92 |
47ba8780 | 138 | |
10a45977 RS |
139 | =head1 WARNING |
140 | ||
141 | The "interpreter-based threads" provided by Perl are not the fast, lightweight | |
142 | system for multitasking that one might expect or hope for. Threads are | |
143 | implemented in a way that make them easy to misuse. Few people know how to | |
144 | use them correctly or will be able to provide help. | |
145 | ||
146 | The use of interpreter-based threads in perl is officially | |
147 | L<discouraged|perlpolicy/discouraged>. | |
148 | ||
47ba8780 AB |
149 | =head1 SYNOPSIS |
150 | ||
3ab14376 JH |
151 | use threads ('yield', |
152 | 'stack_size' => 64*4096, | |
153 | 'exit' => 'threads_only', | |
154 | 'stringify'); | |
47ba8780 | 155 | |
38875929 | 156 | sub start_thread { |
0f1612a7 | 157 | my @args = @_; |
9d9ff5b1 | 158 | print('Thread started: ', join(' ', @args), "\n"); |
38875929 | 159 | } |
fea7688c JH |
160 | my $thr = threads->create('start_thread', 'argument'); |
161 | $thr->join(); | |
0f1612a7 JH |
162 | |
163 | threads->create(sub { print("I am a thread\n"); })->join(); | |
47ba8780 | 164 | |
fea7688c JH |
165 | my $thr2 = async { foreach (@files) { ... } }; |
166 | $thr2->join(); | |
955c272e JH |
167 | if (my $err = $thr2->error()) { |
168 | warn("Thread error: $err\n"); | |
169 | } | |
0f1612a7 | 170 | |
9d9ff5b1 | 171 | # Invoke thread in list context (implicit) so it can return a list |
0f1612a7 | 172 | my ($thr) = threads->create(sub { return (qw/a b c/); }); |
9d9ff5b1 JH |
173 | # or specify list context explicitly |
174 | my $thr = threads->create({'context' => 'list'}, | |
175 | sub { return (qw/a b c/); }); | |
0f1612a7 | 176 | my @results = $thr->join(); |
47ba8780 | 177 | |
fea7688c | 178 | $thr->detach(); |
47ba8780 | 179 | |
69a9b4b8 | 180 | # Get a thread's object |
fea7688c JH |
181 | $thr = threads->self(); |
182 | $thr = threads->object($tid); | |
11c51ed3 | 183 | |
69a9b4b8 | 184 | # Get a thread's ID |
0f1612a7 | 185 | $tid = threads->tid(); |
fea7688c | 186 | $tid = $thr->tid(); |
3ab14376 | 187 | $tid = "$thr"; |
47ba8780 | 188 | |
69a9b4b8 | 189 | # Give other threads a chance to run |
38875929 | 190 | threads->yield(); |
0f1612a7 JH |
191 | yield(); |
192 | ||
69a9b4b8 | 193 | # Lists of non-detached threads |
0f1612a7 | 194 | my @threads = threads->list(); |
fcea4b7c | 195 | my $thread_count = threads->list(); |
f9dff5f5 | 196 | |
ead32952 JH |
197 | my @running = threads->list(threads::running); |
198 | my @joinable = threads->list(threads::joinable); | |
199 | ||
69a9b4b8 | 200 | # Test thread objects |
0f1612a7 JH |
201 | if ($thr1 == $thr2) { |
202 | ... | |
203 | } | |
678a9b6c | 204 | |
69a9b4b8 | 205 | # Manage thread stack size |
514612b7 JH |
206 | $stack_size = threads->get_stack_size(); |
207 | $old_size = threads->set_stack_size(32*4096); | |
208 | ||
9d9ff5b1 JH |
209 | # Create a thread with a specific context and stack size |
210 | my $thr = threads->create({ 'context' => 'list', | |
69a9b4b8 RGS |
211 | 'stack_size' => 32*4096, |
212 | 'exit' => 'thread_only' }, | |
9d9ff5b1 | 213 | \&foo); |
ead32952 JH |
214 | |
215 | # Get thread's context | |
216 | my $wantarray = $thr->wantarray(); | |
217 | ||
218 | # Check thread's state | |
219 | if ($thr->is_running()) { | |
220 | sleep(1); | |
221 | } | |
222 | if ($thr->is_joinable()) { | |
223 | $thr->join(); | |
224 | } | |
9d9ff5b1 | 225 | |
69a9b4b8 | 226 | # Send a signal to a thread |
c0003851 JH |
227 | $thr->kill('SIGUSR1'); |
228 | ||
69a9b4b8 | 229 | # Exit a thread |
4dcb9e53 JH |
230 | threads->exit(); |
231 | ||
47ba8780 AB |
232 | =head1 DESCRIPTION |
233 | ||
3350824e JH |
234 | Since Perl 5.8, thread programming has been available using a model called |
235 | I<interpreter threads> which provides a new Perl interpreter for each | |
236 | thread, and, by default, results in no data or state information being shared | |
237 | between threads. | |
11c51ed3 | 238 | |
3350824e JH |
239 | (Prior to Perl 5.8, I<5005threads> was available through the C<Thread.pm> API. |
240 | This threading model has been deprecated, and was removed as of Perl 5.10.0.) | |
11c51ed3 | 241 | |
3350824e JH |
242 | As just mentioned, all variables are, by default, thread local. To use shared |
243 | variables, you need to also load L<threads::shared>: | |
6ebc233e RGS |
244 | |
245 | use threads; | |
246 | use threads::shared; | |
11c51ed3 | 247 | |
3350824e JH |
248 | When loading L<threads::shared>, you must C<use threads> before you |
249 | C<use threads::shared>. (C<threads> will emit a warning if you do it the | |
250 | other way around.) | |
251 | ||
252 | It is strongly recommended that you enable threads via C<use threads> as early | |
253 | as possible in your script. | |
254 | ||
255 | If needed, scripts can be written so as to run on both threaded and | |
256 | non-threaded Perls: | |
257 | ||
258 | my $can_use_threads = eval 'use threads; 1'; | |
259 | if ($can_use_threads) { | |
260 | # Do processing using threads | |
261 | ... | |
262 | } else { | |
263 | # Do it without using threads | |
264 | ... | |
265 | } | |
47ba8780 AB |
266 | |
267 | =over | |
268 | ||
0f1612a7 | 269 | =item $thr = threads->create(FUNCTION, ARGS) |
47ba8780 | 270 | |
0f1612a7 JH |
271 | This will create a new thread that will begin execution with the specified |
272 | entry point function, and give it the I<ARGS> list as parameters. It will | |
273 | return the corresponding threads object, or C<undef> if thread creation failed. | |
47ba8780 | 274 | |
0f1612a7 JH |
275 | I<FUNCTION> may either be the name of a function, an anonymous subroutine, or |
276 | a code ref. | |
47ba8780 | 277 | |
0f1612a7 JH |
278 | my $thr = threads->create('func_name', ...); |
279 | # or | |
280 | my $thr = threads->create(sub { ... }, ...); | |
281 | # or | |
282 | my $thr = threads->create(\&func, ...); | |
93512b4d | 283 | |
0f1612a7 JH |
284 | The C<-E<gt>new()> method is an alias for C<-E<gt>create()>. |
285 | ||
286 | =item $thr->join() | |
287 | ||
288 | This will wait for the corresponding thread to complete its execution. When | |
289 | the thread finishes, C<-E<gt>join()> will return the return value(s) of the | |
290 | entry point function. | |
291 | ||
9d9ff5b1 JH |
292 | The context (void, scalar or list) for the return value(s) for C<-E<gt>join()> |
293 | is determined at the time of thread creation. | |
0f1612a7 | 294 | |
9d9ff5b1 | 295 | # Create thread in list context (implicit) |
0f1612a7 JH |
296 | my ($thr1) = threads->create(sub { |
297 | my @results = qw(a b c); | |
298 | return (@results); | |
9d9ff5b1 JH |
299 | }); |
300 | # or (explicit) | |
301 | my $thr1 = threads->create({'context' => 'list'}, | |
302 | sub { | |
303 | my @results = qw(a b c); | |
304 | return (@results); | |
305 | }); | |
0f1612a7 JH |
306 | # Retrieve list results from thread |
307 | my @res1 = $thr1->join(); | |
308 | ||
9d9ff5b1 | 309 | # Create thread in scalar context (implicit) |
0f1612a7 JH |
310 | my $thr2 = threads->create(sub { |
311 | my $result = 42; | |
312 | return ($result); | |
9d9ff5b1 | 313 | }); |
0f1612a7 JH |
314 | # Retrieve scalar result from thread |
315 | my $res2 = $thr2->join(); | |
316 | ||
9d9ff5b1 JH |
317 | # Create a thread in void context (explicit) |
318 | my $thr3 = threads->create({'void' => 1}, | |
319 | sub { print("Hello, world\n"); }); | |
320 | # Join the thread in void context (i.e., no return value) | |
321 | $thr3->join(); | |
322 | ||
323 | See L</"THREAD CONTEXT"> for more details. | |
324 | ||
4dcb9e53 JH |
325 | If the program exits without all threads having either been joined or |
326 | detached, then a warning will be issued. | |
93512b4d | 327 | |
fcea4b7c JH |
328 | Calling C<-E<gt>join()> or C<-E<gt>detach()> on an already joined thread will |
329 | cause an error to be thrown. | |
47ba8780 | 330 | |
fcea4b7c | 331 | =item $thr->detach() |
47ba8780 | 332 | |
fcea4b7c | 333 | Makes the thread unjoinable, and causes any eventual return value to be |
4dcb9e53 JH |
334 | discarded. When the program exits, any detached threads that are still |
335 | running are silently terminated. | |
336 | ||
337 | If the program exits without all threads having either been joined or | |
338 | detached, then a warning will be issued. | |
fcea4b7c JH |
339 | |
340 | Calling C<-E<gt>join()> or C<-E<gt>detach()> on an already detached thread | |
341 | will cause an error to be thrown. | |
0f1612a7 JH |
342 | |
343 | =item threads->detach() | |
344 | ||
345 | Class method that allows a thread to detach itself. | |
346 | ||
fcea4b7c | 347 | =item threads->self() |
47ba8780 | 348 | |
fcea4b7c | 349 | Class method that allows a thread to obtain its own I<threads> object. |
47ba8780 | 350 | |
0f1612a7 JH |
351 | =item $thr->tid() |
352 | ||
353 | Returns the ID of the thread. Thread IDs are unique integers with the main | |
354 | thread in a program being 0, and incrementing by 1 for every thread created. | |
47ba8780 | 355 | |
0f1612a7 | 356 | =item threads->tid() |
38875929 | 357 | |
0f1612a7 | 358 | Class method that allows a thread to obtain its own ID. |
47ba8780 | 359 | |
3ab14376 JH |
360 | =item "$thr" |
361 | ||
362 | If you add the C<stringify> import option to your C<use threads> declaration, | |
363 | then using a threads object in a string or a string context (e.g., as a hash | |
364 | key) will cause its ID to be used as the value: | |
365 | ||
5c6ff896 | 366 | use threads qw(stringify); |
3ab14376 | 367 | |
5c6ff896 JH |
368 | my $thr = threads->create(...); |
369 | print("Thread $thr started...\n"); # Prints out: Thread 1 started... | |
3ab14376 | 370 | |
0f1612a7 | 371 | =item threads->object($tid) |
8c9849ff | 372 | |
0f1612a7 | 373 | This will return the I<threads> object for the I<active> thread associated |
b91a79b9 S |
374 | with the specified thread ID. If C<$tid> is the value for the current thread, |
375 | then this call works the same as C<-E<gt>self()>. Otherwise, returns C<undef> | |
376 | if there is no thread associated with the TID, if the thread is joined or | |
377 | detached, if no TID is specified or if the specified TID is undef. | |
8c9849ff | 378 | |
fcea4b7c | 379 | =item threads->yield() |
f9dff5f5 | 380 | |
38875929 DM |
381 | This is a suggestion to the OS to let this thread yield CPU time to other |
382 | threads. What actually happens is highly dependent upon the underlying | |
383 | thread implementation. | |
f9dff5f5 | 384 | |
fcea4b7c | 385 | You may do C<use threads qw(yield)>, and then just use C<yield()> in your |
70f2e746 DM |
386 | code. |
387 | ||
f4cc38af | 388 | =item threads->list() |
678a9b6c | 389 | |
ead32952 JH |
390 | =item threads->list(threads::all) |
391 | ||
392 | =item threads->list(threads::running) | |
393 | ||
394 | =item threads->list(threads::joinable) | |
395 | ||
396 | With no arguments (or using C<threads::all>) and in a list context, returns a | |
397 | list of all non-joined, non-detached I<threads> objects. In a scalar context, | |
398 | returns a count of the same. | |
399 | ||
400 | With a I<true> argument (using C<threads::running>), returns a list of all | |
8718f9a1 | 401 | non-joined, non-detached I<threads> objects that are still running. |
ead32952 JH |
402 | |
403 | With a I<false> argument (using C<threads::joinable>), returns a list of all | |
404 | non-joined, non-detached I<threads> objects that have finished running (i.e., | |
405 | for which C<-E<gt>join()> will not I<block>). | |
678a9b6c | 406 | |
0f1612a7 JH |
407 | =item $thr1->equal($thr2) |
408 | ||
409 | Tests if two threads objects are the same thread or not. This is overloaded | |
fcea4b7c | 410 | to the more natural forms: |
0f1612a7 JH |
411 | |
412 | if ($thr1 == $thr2) { | |
413 | print("Threads are the same\n"); | |
414 | } | |
fcea4b7c JH |
415 | # or |
416 | if ($thr1 != $thr2) { | |
417 | print("Threads differ\n"); | |
418 | } | |
0f1612a7 JH |
419 | |
420 | (Thread comparison is based on thread IDs.) | |
421 | ||
386c44e5 AB |
422 | =item async BLOCK; |
423 | ||
424 | C<async> creates a thread to execute the block immediately following | |
fcea4b7c | 425 | it. This block is treated as an anonymous subroutine, and so must have a |
5cbb7319 | 426 | semicolon after the closing brace. Like C<threads-E<gt>create()>, C<async> |
fcea4b7c | 427 | returns a I<threads> object. |
386c44e5 | 428 | |
955c272e JH |
429 | =item $thr->error() |
430 | ||
431 | Threads are executed in an C<eval> context. This method will return C<undef> | |
432 | if the thread terminates I<normally>. Otherwise, it returns the value of | |
433 | C<$@> associated with the thread's execution status in its C<eval> context. | |
434 | ||
f4cc38af JH |
435 | =item $thr->_handle() |
436 | ||
afb37b32 JH |
437 | This I<private> method returns a pointer (i.e., the memory location expressed |
438 | as an unsigned integer) to the internal thread structure associated with a | |
439 | threads object. For Win32, this is a pointer to the C<HANDLE> value returned | |
440 | by C<CreateThread> (i.e., C<HANDLE *>); for other platforms, it is a pointer | |
441 | to the C<pthread_t> structure used in the C<pthread_create> call (i.e., | |
442 | C<pthread_t *>). | |
f4cc38af JH |
443 | |
444 | This method is of no use for general Perl threads programming. Its intent is | |
445 | to provide other (XS-based) thread modules with the capability to access, and | |
446 | possibly manipulate, the underlying thread structure associated with a Perl | |
447 | thread. | |
448 | ||
449 | =item threads->_handle() | |
450 | ||
451 | Class method that allows a thread to obtain its own I<handle>. | |
452 | ||
47ba8780 AB |
453 | =back |
454 | ||
69a9b4b8 RGS |
455 | =head1 EXITING A THREAD |
456 | ||
457 | The usual method for terminating a thread is to | |
458 | L<return()|perlfunc/"return EXPR"> from the entry point function with the | |
459 | appropriate return value(s). | |
460 | ||
461 | =over | |
462 | ||
463 | =item threads->exit() | |
464 | ||
465 | If needed, a thread can be exited at any time by calling | |
466 | C<threads-E<gt>exit()>. This will cause the thread to return C<undef> in a | |
467 | scalar context, or the empty list in a list context. | |
468 | ||
469 | When called from the I<main> thread, this behaves the same as C<exit(0)>. | |
470 | ||
471 | =item threads->exit(status) | |
472 | ||
473 | When called from a thread, this behaves like C<threads-E<gt>exit()> (i.e., the | |
474 | exit status code is ignored). | |
475 | ||
476 | When called from the I<main> thread, this behaves the same as C<exit(status)>. | |
477 | ||
478 | =item die() | |
479 | ||
480 | Calling C<die()> in a thread indicates an abnormal exit for the thread. Any | |
481 | C<$SIG{__DIE__}> handler in the thread will be called first, and then the | |
482 | thread will exit with a warning message that will contain any arguments passed | |
483 | in the C<die()> call. | |
484 | ||
485 | =item exit(status) | |
486 | ||
487 | Calling L<exit()|perlfunc/"exit EXPR"> inside a thread causes the whole | |
488 | application to terminate. Because of this, the use of C<exit()> inside | |
489 | threaded code, or in modules that might be used in threaded applications, is | |
490 | strongly discouraged. | |
491 | ||
492 | If C<exit()> really is needed, then consider using the following: | |
493 | ||
60bd5ef6 | 494 | threads->exit() if threads->can('exit'); # Thread friendly |
69a9b4b8 RGS |
495 | exit(status); |
496 | ||
5cbb7319 | 497 | =item use threads 'exit' => 'threads_only' |
69a9b4b8 RGS |
498 | |
499 | This globally overrides the default behavior of calling C<exit()> inside a | |
500 | thread, and effectively causes such calls to behave the same as | |
501 | C<threads-E<gt>exit()>. In other words, with this setting, calling C<exit()> | |
502 | causes only the thread to terminate. | |
503 | ||
504 | Because of its global effect, this setting should not be used inside modules | |
505 | or the like. | |
506 | ||
507 | The I<main> thread is unaffected by this setting. | |
508 | ||
509 | =item threads->create({'exit' => 'thread_only'}, ...) | |
510 | ||
511 | This overrides the default behavior of C<exit()> inside the newly created | |
512 | thread only. | |
513 | ||
514 | =item $thr->set_thread_exit_only(boolean) | |
515 | ||
516 | This can be used to change the I<exit thread only> behavior for a thread after | |
5cbb7319 RGS |
517 | it has been created. With a I<true> argument, C<exit()> will cause only the |
518 | thread to exit. With a I<false> argument, C<exit()> will terminate the | |
69a9b4b8 RGS |
519 | application. |
520 | ||
521 | The I<main> thread is unaffected by this call. | |
522 | ||
523 | =item threads->set_thread_exit_only(boolean) | |
524 | ||
5cbb7319 | 525 | Class method for use inside a thread to change its own behavior for C<exit()>. |
69a9b4b8 RGS |
526 | |
527 | The I<main> thread is unaffected by this call. | |
528 | ||
529 | =back | |
530 | ||
ead32952 JH |
531 | =head1 THREAD STATE |
532 | ||
533 | The following boolean methods are useful in determining the I<state> of a | |
534 | thread. | |
535 | ||
536 | =over | |
537 | ||
538 | =item $thr->is_running() | |
539 | ||
540 | Returns true if a thread is still running (i.e., if its entry point function | |
5cbb7319 | 541 | has not yet finished or exited). |
ead32952 JH |
542 | |
543 | =item $thr->is_joinable() | |
544 | ||
545 | Returns true if the thread has finished running, is not detached and has not | |
5cbb7319 RGS |
546 | yet been joined. In other words, the thread is ready to be joined, and a call |
547 | to C<$thr-E<gt>join()> will not I<block>. | |
ead32952 JH |
548 | |
549 | =item $thr->is_detached() | |
550 | ||
551 | Returns true if the thread has been detached. | |
552 | ||
553 | =item threads->is_detached() | |
554 | ||
555 | Class method that allows a thread to determine whether or not it is detached. | |
556 | ||
557 | =back | |
558 | ||
9d9ff5b1 JH |
559 | =head1 THREAD CONTEXT |
560 | ||
561 | As with subroutines, the type of value returned from a thread's entry point | |
562 | function may be determined by the thread's I<context>: list, scalar or void. | |
563 | The thread's context is determined at thread creation. This is necessary so | |
564 | that the context is available to the entry point function via | |
206f4df7 | 565 | L<wantarray()|perlfunc/"wantarray">. The thread may then specify a value of |
9d9ff5b1 JH |
566 | the appropriate type to be returned from C<-E<gt>join()>. |
567 | ||
568 | =head2 Explicit context | |
569 | ||
570 | Because thread creation and thread joining may occur in different contexts, it | |
571 | may be desirable to state the context explicitly to the thread's entry point | |
5cbb7319 | 572 | function. This may be done by calling C<-E<gt>create()> with a hash reference |
9d9ff5b1 JH |
573 | as the first argument: |
574 | ||
575 | my $thr = threads->create({'context' => 'list'}, \&foo); | |
576 | ... | |
577 | my @results = $thr->join(); | |
578 | ||
579 | In the above, the threads object is returned to the parent thread in scalar | |
580 | context, and the thread's entry point function C<foo> will be called in list | |
da140a40 JH |
581 | (array) context such that the parent thread can receive a list (array) from |
582 | the C<-E<gt>join()> call. (C<'array'> is synonymous with C<'list'>.) | |
583 | ||
584 | Similarly, if you need the threads object, but your thread will not be | |
9d9ff5b1 JH |
585 | returning a value (i.e., I<void> context), you would do the following: |
586 | ||
587 | my $thr = threads->create({'context' => 'void'}, \&foo); | |
588 | ... | |
589 | $thr->join(); | |
590 | ||
5cbb7319 | 591 | The context type may also be used as the I<key> in the hash reference followed |
9d9ff5b1 JH |
592 | by a I<true> value: |
593 | ||
594 | threads->create({'scalar' => 1}, \&foo); | |
595 | ... | |
596 | my ($thr) = threads->list(); | |
597 | my $result = $thr->join(); | |
598 | ||
599 | =head2 Implicit context | |
600 | ||
601 | If not explicitly stated, the thread's context is implied from the context | |
602 | of the C<-E<gt>create()> call: | |
603 | ||
604 | # Create thread in list context | |
605 | my ($thr) = threads->create(...); | |
606 | ||
607 | # Create thread in scalar context | |
608 | my $thr = threads->create(...); | |
609 | ||
610 | # Create thread in void context | |
611 | threads->create(...); | |
612 | ||
ead32952 JH |
613 | =head2 $thr->wantarray() |
614 | ||
615 | This returns the thread's context in the same manner as | |
616 | L<wantarray()|perlfunc/"wantarray">. | |
617 | ||
618 | =head2 threads->wantarray() | |
619 | ||
5cbb7319 RGS |
620 | Class method to return the current thread's context. This returns the same |
621 | value as running L<wantarray()|perlfunc/"wantarray"> inside the current | |
622 | thread's entry point function. | |
ead32952 | 623 | |
514612b7 JH |
624 | =head1 THREAD STACK SIZE |
625 | ||
626 | The default per-thread stack size for different platforms varies | |
627 | significantly, and is almost always far more than is needed for most | |
628 | applications. On Win32, Perl's makefile explicitly sets the default stack to | |
629 | 16 MB; on most other platforms, the system default is used, which again may be | |
630 | much larger than is needed. | |
631 | ||
632 | By tuning the stack size to more accurately reflect your application's needs, | |
633 | you may significantly reduce your application's memory usage, and increase the | |
634 | number of simultaneously running threads. | |
635 | ||
5cbb7319 RGS |
636 | Note that on Windows, address space allocation granularity is 64 KB, |
637 | therefore, setting the stack smaller than that on Win32 Perl will not save any | |
638 | more memory. | |
514612b7 JH |
639 | |
640 | =over | |
641 | ||
642 | =item threads->get_stack_size(); | |
643 | ||
644 | Returns the current default per-thread stack size. The default is zero, which | |
645 | means the system default stack size is currently in use. | |
646 | ||
647 | =item $size = $thr->get_stack_size(); | |
648 | ||
649 | Returns the stack size for a particular thread. A return value of zero | |
650 | indicates the system default stack size was used for the thread. | |
651 | ||
652 | =item $old_size = threads->set_stack_size($new_size); | |
653 | ||
654 | Sets a new default per-thread stack size, and returns the previous setting. | |
655 | ||
656 | Some platforms have a minimum thread stack size. Trying to set the stack size | |
657 | below this value will result in a warning, and the minimum stack size will be | |
658 | used. | |
659 | ||
660 | Some Linux platforms have a maximum stack size. Setting too large of a stack | |
661 | size will cause thread creation to fail. | |
662 | ||
663 | If needed, C<$new_size> will be rounded up to the next multiple of the memory | |
664 | page size (usually 4096 or 8192). | |
665 | ||
666 | Threads created after the stack size is set will then either call | |
667 | C<pthread_attr_setstacksize()> I<(for pthreads platforms)>, or supply the | |
668 | stack size to C<CreateThread()> I<(for Win32 Perl)>. | |
669 | ||
670 | (Obviously, this call does not affect any currently extant threads.) | |
671 | ||
672 | =item use threads ('stack_size' => VALUE); | |
673 | ||
674 | This sets the default per-thread stack size at the start of the application. | |
675 | ||
676 | =item $ENV{'PERL5_ITHREADS_STACK_SIZE'} | |
677 | ||
678 | The default per-thread stack size may be set at the start of the application | |
679 | through the use of the environment variable C<PERL5_ITHREADS_STACK_SIZE>: | |
680 | ||
681 | PERL5_ITHREADS_STACK_SIZE=1048576 | |
682 | export PERL5_ITHREADS_STACK_SIZE | |
683 | perl -e'use threads; print(threads->get_stack_size(), "\n")' | |
684 | ||
685 | This value overrides any C<stack_size> parameter given to C<use threads>. Its | |
686 | primary purpose is to permit setting the per-thread stack size for legacy | |
687 | threaded applications. | |
688 | ||
689 | =item threads->create({'stack_size' => VALUE}, FUNCTION, ARGS) | |
690 | ||
5cbb7319 RGS |
691 | To specify a particular stack size for any individual thread, call |
692 | C<-E<gt>create()> with a hash reference as the first argument: | |
9d9ff5b1 JH |
693 | |
694 | my $thr = threads->create({'stack_size' => 32*4096}, \&foo, @args); | |
514612b7 JH |
695 | |
696 | =item $thr2 = $thr1->create(FUNCTION, ARGS) | |
697 | ||
698 | This creates a new thread (C<$thr2>) that inherits the stack size from an | |
699 | existing thread (C<$thr1>). This is shorthand for the following: | |
700 | ||
701 | my $stack_size = $thr1->get_stack_size(); | |
702 | my $thr2 = threads->create({'stack_size' => $stack_size}, FUNCTION, ARGS); | |
703 | ||
704 | =back | |
705 | ||
c0003851 JH |
706 | =head1 THREAD SIGNALLING |
707 | ||
9d9ff5b1 | 708 | When safe signals is in effect (the default behavior - see L</"Unsafe signals"> |
1152d448 JH |
709 | for more details), then signals may be sent and acted upon by individual |
710 | threads. | |
c0003851 JH |
711 | |
712 | =over 4 | |
713 | ||
714 | =item $thr->kill('SIG...'); | |
715 | ||
716 | Sends the specified signal to the thread. Signal names and (positive) signal | |
717 | numbers are the same as those supported by | |
718 | L<kill()|perlfunc/"kill SIGNAL, LIST">. For example, 'SIGTERM', 'TERM' and | |
719 | (depending on the OS) 15 are all valid arguments to C<-E<gt>kill()>. | |
720 | ||
721 | Returns the thread object to allow for method chaining: | |
722 | ||
723 | $thr->kill('SIG...')->join(); | |
724 | ||
725 | =back | |
726 | ||
727 | Signal handlers need to be set up in the threads for the signals they are | |
728 | expected to act upon. Here's an example for I<cancelling> a thread: | |
729 | ||
730 | use threads; | |
731 | ||
c0003851 JH |
732 | sub thr_func |
733 | { | |
734 | # Thread 'cancellation' signal handler | |
c608f8c0 | 735 | $SIG{'KILL'} = sub { threads->exit(); }; |
c0003851 JH |
736 | |
737 | ... | |
738 | } | |
739 | ||
740 | # Create a thread | |
741 | my $thr = threads->create('thr_func'); | |
742 | ||
743 | ... | |
744 | ||
745 | # Signal the thread to terminate, and then detach | |
746 | # it so that it will get cleaned up automatically | |
747 | $thr->kill('KILL')->detach(); | |
748 | ||
404aaa48 JH |
749 | Here's another simplistic example that illustrates the use of thread |
750 | signalling in conjunction with a semaphore to provide rudimentary I<suspend> | |
751 | and I<resume> capabilities: | |
c0003851 JH |
752 | |
753 | use threads; | |
754 | use Thread::Semaphore; | |
755 | ||
756 | sub thr_func | |
757 | { | |
758 | my $sema = shift; | |
759 | ||
760 | # Thread 'suspend/resume' signal handler | |
761 | $SIG{'STOP'} = sub { | |
762 | $sema->down(); # Thread suspended | |
763 | $sema->up(); # Thread resumes | |
764 | }; | |
765 | ||
766 | ... | |
767 | } | |
768 | ||
5cbb7319 | 769 | # Create a semaphore and pass it to a thread |
c0003851 JH |
770 | my $sema = Thread::Semaphore->new(); |
771 | my $thr = threads->create('thr_func', $sema); | |
772 | ||
773 | # Suspend the thread | |
774 | $sema->down(); | |
775 | $thr->kill('STOP'); | |
776 | ||
777 | ... | |
778 | ||
779 | # Allow the thread to continue | |
780 | $sema->up(); | |
781 | ||
404aaa48 JH |
782 | CAVEAT: The thread signalling capability provided by this module does not |
783 | actually send signals via the OS. It I<emulates> signals at the Perl-level | |
784 | such that signal handlers are called in the appropriate thread. For example, | |
785 | sending C<$thr-E<gt>kill('STOP')> does not actually suspend a thread (or the | |
786 | whole process), but does cause a C<$SIG{'STOP'}> handler to be called in that | |
787 | thread (as illustrated above). | |
788 | ||
789 | As such, signals that would normally not be appropriate to use in the | |
790 | C<kill()> command (e.g., C<kill('KILL', $$)>) are okay to use with the | |
791 | C<-E<gt>kill()> method (again, as illustrated above). | |
792 | ||
793 | Correspondingly, sending a signal to a thread does not disrupt the operation | |
794 | the thread is currently working on: The signal will be acted upon after the | |
c0003851 JH |
795 | current operation has completed. For instance, if the thread is I<stuck> on |
796 | an I/O call, sending it a signal will not cause the I/O call to be interrupted | |
797 | such that the signal is acted up immediately. | |
798 | ||
99f57afc | 799 | Sending a signal to a terminated/finished thread is ignored. |
69a9b4b8 | 800 | |
e4f9f4fe JH |
801 | =head1 WARNINGS |
802 | ||
803 | =over 4 | |
804 | ||
4dcb9e53 | 805 | =item Perl exited with active threads: |
e4f9f4fe | 806 | |
4dcb9e53 JH |
807 | If the program exits without all threads having either been joined or |
808 | detached, then this warning will be issued. | |
809 | ||
69a9b4b8 RGS |
810 | NOTE: If the I<main> thread exits, then this warning cannot be suppressed |
811 | using C<no warnings 'threads';> as suggested below. | |
e4f9f4fe | 812 | |
c0003851 JH |
813 | =item Thread creation failed: pthread_create returned # |
814 | ||
815 | See the appropriate I<man> page for C<pthread_create> to determine the actual | |
816 | cause for the failure. | |
817 | ||
818 | =item Thread # terminated abnormally: ... | |
819 | ||
820 | A thread terminated in some manner other than just returning from its entry | |
955c272e | 821 | point function, or by using C<threads-E<gt>exit()>. For example, the thread |
5cbb7319 | 822 | may have terminated because of an error, or by using C<die>. |
c0003851 | 823 | |
514612b7 JH |
824 | =item Using minimum thread stack size of # |
825 | ||
826 | Some platforms have a minimum thread stack size. Trying to set the stack size | |
827 | below this value will result in the above warning, and the stack size will be | |
828 | set to the minimum. | |
829 | ||
c0003851 JH |
830 | =item Thread creation failed: pthread_attr_setstacksize(I<SIZE>) returned 22 |
831 | ||
832 | The specified I<SIZE> exceeds the system's maximum stack size. Use a smaller | |
833 | value for the stack size. | |
834 | ||
e4f9f4fe | 835 | =back |
47ba8780 | 836 | |
c0003851 JH |
837 | If needed, thread warnings can be suppressed by using: |
838 | ||
839 | no warnings 'threads'; | |
840 | ||
841 | in the appropriate scope. | |
842 | ||
0f1612a7 JH |
843 | =head1 ERRORS |
844 | ||
845 | =over 4 | |
846 | ||
fcea4b7c | 847 | =item This Perl not built to support threads |
678a9b6c | 848 | |
0f1612a7 JH |
849 | The particular copy of Perl that you're trying to use was not built using the |
850 | C<useithreads> configuration option. | |
678a9b6c | 851 | |
0f1612a7 JH |
852 | Having threads support requires all of Perl and all of the XS modules in the |
853 | Perl installation to be rebuilt; it is not just a question of adding the | |
854 | L<threads> module (i.e., threaded and non-threaded Perls are binary | |
99f57afc | 855 | incompatible). |
0f1612a7 | 856 | |
514612b7 JH |
857 | =item Cannot change stack size of an existing thread |
858 | ||
859 | The stack size of currently extant threads cannot be changed, therefore, the | |
860 | following results in the above error: | |
861 | ||
862 | $thr->set_stack_size($size); | |
863 | ||
4dcb9e53 | 864 | =item Cannot signal threads without safe signals |
514612b7 | 865 | |
1152d448 | 866 | Safe signals must be in effect to use the C<-E<gt>kill()> signalling method. |
9d9ff5b1 | 867 | See L</"Unsafe signals"> for more details. |
c0003851 JH |
868 | |
869 | =item Unrecognized signal name: ... | |
870 | ||
871 | The particular copy of Perl that you're trying to use does not support the | |
872 | specified signal being used in a C<-E<gt>kill()> call. | |
514612b7 | 873 | |
0f1612a7 | 874 | =back |
47ba8780 | 875 | |
b9c1db01 JH |
876 | =head1 BUGS AND LIMITATIONS |
877 | ||
878 | Before you consider posting a bug report, please consult, and possibly post a | |
879 | message to the discussion forum to see if what you've encountered is a known | |
880 | problem. | |
5c6ff896 JH |
881 | |
882 | =over | |
883 | ||
938aad41 | 884 | =item Thread-safe modules |
c527c90b JH |
885 | |
886 | See L<perlmod/"Making your module threadsafe"> when creating modules that may | |
887 | be used in threaded applications, especially if those modules use non-Perl | |
888 | data, or XS code. | |
889 | ||
938aad41 | 890 | =item Using non-thread-safe modules |
5c6ff896 | 891 | |
938aad41 JH |
892 | Unfortunately, you may encounter Perl modules that are not I<thread-safe>. |
893 | For example, they may crash the Perl interpreter during execution, or may dump | |
5c6ff896 JH |
894 | core on termination. Depending on the module and the requirements of your |
895 | application, it may be possible to work around such difficulties. | |
896 | ||
897 | If the module will only be used inside a thread, you can try loading the | |
898 | module from inside the thread entry point function using C<require> (and | |
899 | C<import> if needed): | |
900 | ||
901 | sub thr_func | |
902 | { | |
903 | require Unsafe::Module | |
f3086ff0 | 904 | # Unsafe::Module->import(...); |
5c6ff896 JH |
905 | |
906 | .... | |
907 | } | |
908 | ||
955c272e JH |
909 | If the module is needed inside the I<main> thread, try modifying your |
910 | application so that the module is loaded (again using C<require> and | |
f3086ff0 JH |
911 | C<-E<gt>import()>) after any threads are started, and in such a way that no |
912 | other threads are started afterwards. | |
5c6ff896 JH |
913 | |
914 | If the above does not work, or is not adequate for your application, then file | |
915 | a bug report on L<http://rt.cpan.org/Public/> against the problematic module. | |
916 | ||
b91a79b9 S |
917 | =item Memory consumption |
918 | ||
919 | On most systems, frequent and continual creation and destruction of threads | |
920 | can lead to ever-increasing growth in the memory footprint of the Perl | |
921 | interpreter. While it is simple to just launch threads and then | |
922 | C<-E<gt>join()> or C<-E<gt>detach()> them, for long-lived applications, it is | |
923 | better to maintain a pool of threads, and to reuse them for the work needed, | |
924 | using L<queues|Thread::Queue> to notify threads of pending work. The CPAN | |
925 | distribution of this module contains a simple example | |
926 | (F<examples/pool_reuse.pl>) illustrating the creation, use and monitoring of a | |
927 | pool of I<reusable> threads. | |
928 | ||
f3086ff0 JH |
929 | =item Current working directory |
930 | ||
931 | On all platforms except MSWin32, the setting for the current working directory | |
932 | is shared among all threads such that changing it in one thread (e.g., using | |
933 | C<chdir()>) will affect all the threads in the application. | |
934 | ||
935 | On MSWin32, each thread maintains its own the current working directory | |
936 | setting. | |
937 | ||
938 | =item Environment variables | |
939 | ||
940 | Currently, on all platforms except MSWin32, all I<system> calls (e.g., using | |
941 | C<system()> or back-ticks) made from threads use the environment variable | |
942 | settings from the I<main> thread. In other words, changes made to C<%ENV> in | |
943 | a thread will not be visible in I<system> calls made by that thread. | |
944 | ||
945 | To work around this, set environment variables as part of the I<system> call. | |
946 | For example: | |
947 | ||
948 | my $msg = 'hello'; | |
949 | system("FOO=$msg; echo \$FOO"); # Outputs 'hello' to STDOUT | |
950 | ||
951 | On MSWin32, each thread maintains its own set of environment variables. | |
952 | ||
794373aa JH |
953 | =item Catching signals |
954 | ||
955 | Signals are I<caught> by the main thread (thread ID = 0) of a script. | |
956 | Therefore, setting up signal handlers in threads for purposes other than | |
957 | L</"THREAD SIGNALLING"> as documented above will not accomplish what is | |
958 | intended. | |
959 | ||
960 | This is especially true if trying to catch C<SIGALRM> in a thread. To handle | |
961 | alarms in threads, set up a signal handler in the main thread, and then use | |
962 | L</"THREAD SIGNALLING"> to relay the signal to the thread: | |
963 | ||
964 | # Create thread with a task that may time out | |
afb37b32 | 965 | my $thr = threads->create(sub { |
794373aa JH |
966 | threads->yield(); |
967 | eval { | |
968 | $SIG{ALRM} = sub { die("Timeout\n"); }; | |
969 | alarm(10); | |
970 | ... # Do work here | |
971 | alarm(0); | |
972 | }; | |
973 | if ($@ =~ /Timeout/) { | |
974 | warn("Task in thread timed out\n"); | |
975 | } | |
976 | }; | |
977 | ||
978 | # Set signal handler to relay SIGALRM to thread | |
979 | $SIG{ALRM} = sub { $thr->kill('ALRM') }; | |
980 | ||
981 | ... # Main thread continues working | |
982 | ||
fcea4b7c | 983 | =item Parent-child threads |
678a9b6c | 984 | |
fcea4b7c JH |
985 | On some platforms, it might not be possible to destroy I<parent> threads while |
986 | there are still existing I<child> threads. | |
678a9b6c | 987 | |
404aaa48 | 988 | =item Creating threads inside special blocks |
88f8c1df | 989 | |
f2e0bb91 JH |
990 | Creating threads inside C<BEGIN>, C<CHECK> or C<INIT> blocks should not be |
991 | relied upon. Depending on the Perl version and the application code, results | |
58a3a76c | 992 | may range from success, to (apparently harmless) warnings of leaked scalar, or |
f2e0bb91 | 993 | all the way up to crashing of the Perl interpreter. |
88f8c1df | 994 | |
1152d448 | 995 | =item Unsafe signals |
47ba8780 | 996 | |
1152d448 JH |
997 | Since Perl 5.8.0, signals have been made safer in Perl by postponing their |
998 | handling until the interpreter is in a I<safe> state. See | |
404aaa48 | 999 | L<perl58delta/"Safe Signals"> and L<perlipc/"Deferred Signals (Safe Signals)"> |
1152d448 JH |
1000 | for more details. |
1001 | ||
1002 | Safe signals is the default behavior, and the old, immediate, unsafe | |
1003 | signalling behavior is only in effect in the following situations: | |
1004 | ||
1005 | =over 4 | |
1006 | ||
5cbb7319 | 1007 | =item * Perl has been built with C<PERL_OLD_SIGNALS> (see C<perl -V>). |
1152d448 JH |
1008 | |
1009 | =item * The environment variable C<PERL_SIGNALS> is set to C<unsafe> (see L<perlrun/"PERL_SIGNALS">). | |
1010 | ||
1011 | =item * The module L<Perl::Unsafe::Signals> is used. | |
1012 | ||
1013 | =back | |
1014 | ||
1015 | If unsafe signals is in effect, then signal handling is not thread-safe, and | |
1016 | the C<-E<gt>kill()> signalling method cannot be used. | |
88f8c1df | 1017 | |
0f1612a7 JH |
1018 | =item Returning closures from threads |
1019 | ||
99f57afc | 1020 | Returning closures from threads should not be relied upon. Depending on the |
f2e0bb91 | 1021 | Perl version and the application code, results may range from success, to |
58a3a76c JH |
1022 | (apparently harmless) warnings of leaked scalar, or all the way up to crashing |
1023 | of the Perl interpreter. | |
0f1612a7 | 1024 | |
955c272e JH |
1025 | =item Returning objects from threads |
1026 | ||
b9c1db01 JH |
1027 | Returning objects from threads does not work. Depending on the classes |
1028 | involved, you may be able to work around this by returning a serialized | |
1029 | version of the object (e.g., using L<Data::Dumper> or L<Storable>), and then | |
7ef93cb2 JH |
1030 | reconstituting it in the joining thread. If you're using Perl 5.10.0 or |
1031 | later, and if the class supports L<shared objects|threads::shared/"OBJECTS">, | |
b91a79b9 | 1032 | you can pass them via L<shared queues|Thread::Queue>. |
955c272e | 1033 | |
561ee912 JH |
1034 | =item END blocks in threads |
1035 | ||
1036 | It is possible to add L<END blocks|perlmod/"BEGIN, UNITCHECK, CHECK, INIT and | |
1037 | END"> to threads by using L<require|perlfunc/"require VERSION"> or | |
1038 | L<eval|perlfunc/"eval EXPR"> with the appropriate code. These C<END> blocks | |
1039 | will then be executed when the thread's interpreter is destroyed (i.e., either | |
1040 | during a C<-E<gt>join()> call, or at program termination). | |
1041 | ||
1042 | However, calling any L<threads> methods in such an C<END> block will most | |
1043 | likely I<fail> (e.g., the application may hang, or generate an error) due to | |
1044 | mutexes that are needed to control functionality within the L<threads> module. | |
1045 | ||
1046 | For this reason, the use of C<END> blocks in threads is B<strongly> | |
1047 | discouraged. | |
1048 | ||
414fa04c JH |
1049 | =item Open directory handles |
1050 | ||
c2053ddb FC |
1051 | In perl 5.14 and higher, on systems other than Windows that do |
1052 | not support the C<fchdir> C function, directory handles (see | |
89cf1afa FC |
1053 | L<opendir|perlfunc/"opendir DIRHANDLE,EXPR">) will not be copied to new |
1054 | threads. You can use the C<d_fchdir> variable in L<Config.pm|Config> to | |
1055 | determine whether your system supports it. | |
1056 | ||
1057 | In prior perl versions, spawning threads with open directory handles would | |
1058 | crash the interpreter. | |
414fa04c JH |
1059 | L<[perl #75154]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=75154> |
1060 | ||
0f1612a7 JH |
1061 | =item Perl Bugs and the CPAN Version of L<threads> |
1062 | ||
5cbb7319 | 1063 | Support for threads extends beyond the code in this module (i.e., |
938aad41 | 1064 | F<threads.pm> and F<threads.xs>), and into the Perl interpreter itself. Older |
0f1612a7 JH |
1065 | versions of Perl contain bugs that may manifest themselves despite using the |
1066 | latest version of L<threads> from CPAN. There is no workaround for this other | |
938aad41 | 1067 | than upgrading to the latest version of Perl. |
0f1612a7 | 1068 | |
938aad41 | 1069 | Even with the latest version of Perl, it is known that certain constructs |
c527c90b JH |
1070 | with threads may result in warning messages concerning leaked scalars or |
1071 | unreferenced scalars. However, such warnings are harmless, and may safely be | |
1072 | ignored. | |
1073 | ||
7ef93cb2 JH |
1074 | You can search for L<threads> related bug reports at |
1075 | L<http://rt.cpan.org/Public/>. If needed submit any new bugs, problems, | |
1076 | patches, etc. to: L<http://rt.cpan.org/Public/Dist/Display.html?Name=threads> | |
1077 | ||
47ba8780 AB |
1078 | =back |
1079 | ||
0f1612a7 | 1080 | =head1 REQUIREMENTS |
47ba8780 | 1081 | |
0f1612a7 | 1082 | Perl 5.8.0 or later |
47ba8780 | 1083 | |
0f1612a7 | 1084 | =head1 SEE ALSO |
47ba8780 | 1085 | |
0f1612a7 JH |
1086 | L<threads> Discussion Forum on CPAN: |
1087 | L<http://www.cpanforum.com/dist/threads> | |
47ba8780 | 1088 | |
0f1612a7 | 1089 | L<threads::shared>, L<perlthrtut> |
47ba8780 | 1090 | |
0f1612a7 JH |
1091 | L<http://www.perl.com/pub/a/2002/06/11/threads.html> and |
1092 | L<http://www.perl.com/pub/a/2002/09/04/threads.html> | |
47ba8780 | 1093 | |
0f1612a7 | 1094 | Perl threads mailing list: |
d185f61f | 1095 | L<http://lists.perl.org/list/ithreads.html> |
47ba8780 | 1096 | |
514612b7 JH |
1097 | Stack size discussion: |
1098 | L<http://www.perlmonks.org/?node_id=532956> | |
1099 | ||
0f1612a7 | 1100 | =head1 AUTHOR |
47ba8780 | 1101 | |
0f1612a7 JH |
1102 | Artur Bergman E<lt>sky AT crucially DOT netE<gt> |
1103 | ||
0f1612a7 JH |
1104 | CPAN version produced by Jerry D. Hedden <jdhedden AT cpan DOT org> |
1105 | ||
561ee912 JH |
1106 | =head1 LICENSE |
1107 | ||
1108 | threads is released under the same license as Perl. | |
1109 | ||
0f1612a7 JH |
1110 | =head1 ACKNOWLEDGEMENTS |
1111 | ||
1112 | Richard Soderberg E<lt>perl AT crystalflame DOT netE<gt> - | |
1113 | Helping me out tons, trying to find reasons for races and other weird bugs! | |
1114 | ||
1115 | Simon Cozens E<lt>simon AT brecon DOT co DOT ukE<gt> - | |
1116 | Being there to answer zillions of annoying questions | |
1117 | ||
1118 | Rocco Caputo E<lt>troc AT netrus DOT netE<gt> | |
47ba8780 | 1119 | |
0f1612a7 JH |
1120 | Vipul Ved Prakash E<lt>mail AT vipul DOT netE<gt> - |
1121 | Helping with debugging | |
47ba8780 | 1122 | |
514612b7 JH |
1123 | Dean Arnold E<lt>darnold AT presicient DOT comE<gt> - |
1124 | Stack size API | |
1125 | ||
47ba8780 | 1126 | =cut |