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