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