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