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