Commit | Line | Data |
47ba8780 |
1 | package threads; |
2 | |
32419a4c |
3 | use 5.008; |
fcea4b7c |
4 | |
47ba8780 |
5 | use strict; |
6 | use warnings; |
73e09c8f |
7 | |
d305c2c9 |
8 | our $VERSION = '1.26'; |
fcea4b7c |
9 | my $XS_VERSION = $VERSION; |
10 | $VERSION = eval $VERSION; |
73e09c8f |
11 | |
73e09c8f |
12 | |
fcea4b7c |
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 |
20 | # Declare that we have been loaded |
21 | $threads::threads = 1; |
22 | |
23 | # Complain if 'threads' is loaded after 'threads::shared' |
24 | if ($threads::shared::threads_shared) { |
25 | warn <<'_MSG_'; |
26 | Warning, threads::shared has already been loaded. To |
27 | enable shared variables, 'use threads' must be called |
28 | before threads::shared or any module that uses it. |
29 | _MSG_ |
30 | } |
dab065ea |
31 | } |
32 | |
fc04eb16 |
33 | |
0f1612a7 |
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 |
41 | sub import |
42 | { |
43 | my $class = shift; # Not used |
44 | |
45 | # Exported subroutines |
46 | my @EXPORT = qw(async); |
47 | |
48 | # Handle args |
49 | while (my $sym = shift) { |
514612b7 |
50 | if ($sym =~ /^stack/) { |
51 | threads->set_stack_size(shift); |
52 | |
53 | } elsif ($sym =~ /all/) { |
0f1612a7 |
54 | push(@EXPORT, qw(yield)); |
55 | |
56 | } else { |
57 | push(@EXPORT, $sym); |
58 | } |
59 | } |
60 | |
61 | # Export subroutine names |
62 | my $caller = caller(); |
63 | foreach my $sym (@EXPORT) { |
64 | no strict 'refs'; |
65 | *{$caller.'::'.$sym} = \&{$sym}; |
66 | } |
514612b7 |
67 | |
68 | # Set stack size via environment variable |
69 | if (exists($ENV{'PERL5_ITHREADS_STACK_SIZE'})) { |
70 | threads->set_stack_size($ENV{'PERL5_ITHREADS_STACK_SIZE'}); |
71 | } |
0f1612a7 |
72 | } |
73 | |
74 | |
75 | ### Methods, etc. ### |
47ba8780 |
76 | |
f4cc38af |
77 | # 'new' is an alias for 'create' |
78 | *new = \&create; |
68795e93 |
79 | |
fcea4b7c |
80 | # 'async' is a function alias for the 'threads->create()' method |
81 | sub async (&;@) |
82 | { |
83 | unshift(@_, 'threads'); |
84 | # Use "goto" trick to avoid pad problems from 5.8.1 (fixed in 5.8.2) |
85 | goto &create; |
86 | } |
87 | |
88 | # Thread object equality checking |
89 | use overload ( |
90 | '==' => \&equal, |
91 | '!=' => sub { ! equal(@_) }, |
92 | 'fallback' => 1 |
93 | ); |
94 | |
47ba8780 |
95 | 1; |
0f1612a7 |
96 | |
47ba8780 |
97 | __END__ |
98 | |
99 | =head1 NAME |
100 | |
0f1612a7 |
101 | threads - Perl interpreter-based threads |
102 | |
103 | =head1 VERSION |
104 | |
d305c2c9 |
105 | This document describes threads version 1.26 |
47ba8780 |
106 | |
107 | =head1 SYNOPSIS |
108 | |
514612b7 |
109 | use threads ('yield', 'stack_size' => 64*4096); |
47ba8780 |
110 | |
38875929 |
111 | sub start_thread { |
0f1612a7 |
112 | my @args = @_; |
113 | print "Thread started: @args\n"; |
38875929 |
114 | } |
0f1612a7 |
115 | my $thread = threads->create('start_thread', 'argument'); |
116 | $thread->join(); |
117 | |
118 | threads->create(sub { print("I am a thread\n"); })->join(); |
47ba8780 |
119 | |
38875929 |
120 | my $thread3 = async { foreach (@files) { ... } }; |
0f1612a7 |
121 | $thread3->join(); |
122 | |
123 | # Invoke thread in list context so it can return a list |
124 | my ($thr) = threads->create(sub { return (qw/a b c/); }); |
125 | my @results = $thr->join(); |
47ba8780 |
126 | |
38875929 |
127 | $thread->detach(); |
47ba8780 |
128 | |
38875929 |
129 | $thread = threads->self(); |
0f1612a7 |
130 | $thread = threads->object($tid); |
11c51ed3 |
131 | |
0f1612a7 |
132 | $tid = threads->tid(); |
133 | $tid = threads->self->tid(); |
134 | $tid = $thread->tid(); |
47ba8780 |
135 | |
38875929 |
136 | threads->yield(); |
0f1612a7 |
137 | yield(); |
138 | |
139 | my @threads = threads->list(); |
fcea4b7c |
140 | my $thread_count = threads->list(); |
f9dff5f5 |
141 | |
0f1612a7 |
142 | if ($thr1 == $thr2) { |
143 | ... |
144 | } |
678a9b6c |
145 | |
514612b7 |
146 | $stack_size = threads->get_stack_size(); |
147 | $old_size = threads->set_stack_size(32*4096); |
148 | |
47ba8780 |
149 | =head1 DESCRIPTION |
150 | |
fc04eb16 |
151 | Perl 5.6 introduced something called interpreter threads. Interpreter threads |
152 | are different from I<5005threads> (the thread model of Perl 5.005) by creating |
153 | a new Perl interpreter per thread, and not sharing any data or state between |
154 | threads by default. |
11c51ed3 |
155 | |
fc04eb16 |
156 | Prior to Perl 5.8, this has only been available to people embedding Perl, and |
157 | for emulating fork() on Windows. |
11c51ed3 |
158 | |
fc04eb16 |
159 | The I<threads> API is loosely based on the old Thread.pm API. It is very |
160 | important to note that variables are not shared between threads, all variables |
161 | are by default thread local. To use shared variables one must use |
162 | L<threads::shared>. |
11c51ed3 |
163 | |
fc04eb16 |
164 | It is also important to note that you must enable threads by doing C<use |
165 | threads> as early as possible in the script itself, and that it is not |
166 | possible to enable threading inside an C<eval "">, C<do>, C<require>, or |
167 | C<use>. In particular, if you are intending to share variables with |
168 | L<threads::shared>, you must C<use threads> before you C<use threads::shared>. |
169 | (C<threads> will emit a warning if you do it the other way around.) |
47ba8780 |
170 | |
171 | =over |
172 | |
0f1612a7 |
173 | =item $thr = threads->create(FUNCTION, ARGS) |
47ba8780 |
174 | |
0f1612a7 |
175 | This will create a new thread that will begin execution with the specified |
176 | entry point function, and give it the I<ARGS> list as parameters. It will |
177 | return the corresponding threads object, or C<undef> if thread creation failed. |
47ba8780 |
178 | |
0f1612a7 |
179 | I<FUNCTION> may either be the name of a function, an anonymous subroutine, or |
180 | a code ref. |
47ba8780 |
181 | |
0f1612a7 |
182 | my $thr = threads->create('func_name', ...); |
183 | # or |
184 | my $thr = threads->create(sub { ... }, ...); |
185 | # or |
186 | my $thr = threads->create(\&func, ...); |
93512b4d |
187 | |
0f1612a7 |
188 | The thread may be created in I<list> context, or I<scalar> context as follows: |
189 | |
190 | # Create thread in list context |
191 | my ($thr) = threads->create(...); |
192 | |
193 | # Create thread in scalar context |
194 | my $thr = threads->create(...); |
195 | |
196 | This has consequences for the C<-E<gt>join()> method describe below. |
197 | |
198 | Although a thread may be created in I<void> context, to do so you must |
199 | I<chain> either the C<-E<gt>join()> or C<-E<gt>detach()> method to the |
200 | C<-E<gt>create()> call: |
93512b4d |
201 | |
0f1612a7 |
202 | threads->create(...)->join(); |
47ba8780 |
203 | |
0f1612a7 |
204 | The C<-E<gt>new()> method is an alias for C<-E<gt>create()>. |
205 | |
206 | =item $thr->join() |
207 | |
208 | This will wait for the corresponding thread to complete its execution. When |
209 | the thread finishes, C<-E<gt>join()> will return the return value(s) of the |
210 | entry point function. |
211 | |
212 | The context (void, scalar or list) of the thread creation is also the |
213 | context for C<-E<gt>join()>. This means that if you intend to return an array |
214 | from a thread, you must use C<my ($thr) = threads->create(...)>, and that |
215 | if you intend to return a scalar, you must use C<my $thr = ...>: |
216 | |
217 | # Create thread in list context |
218 | my ($thr1) = threads->create(sub { |
219 | my @results = qw(a b c); |
220 | return (@results); |
221 | }; |
222 | # Retrieve list results from thread |
223 | my @res1 = $thr1->join(); |
224 | |
225 | # Create thread in scalar context |
226 | my $thr2 = threads->create(sub { |
227 | my $result = 42; |
228 | return ($result); |
229 | }; |
230 | # Retrieve scalar result from thread |
231 | my $res2 = $thr2->join(); |
232 | |
233 | If the program exits without all other threads having been either joined or |
234 | detached, then a warning will be issued. (A program exits either because one |
235 | of its threads explicitly calls L<exit()|perlfunc/"exit EXPR">, or in the case |
236 | of the main thread, reaches the end of the main program file.) |
93512b4d |
237 | |
fcea4b7c |
238 | Calling C<-E<gt>join()> or C<-E<gt>detach()> on an already joined thread will |
239 | cause an error to be thrown. |
47ba8780 |
240 | |
fcea4b7c |
241 | =item $thr->detach() |
47ba8780 |
242 | |
fcea4b7c |
243 | Makes the thread unjoinable, and causes any eventual return value to be |
244 | discarded. |
245 | |
246 | Calling C<-E<gt>join()> or C<-E<gt>detach()> on an already detached thread |
247 | will cause an error to be thrown. |
0f1612a7 |
248 | |
249 | =item threads->detach() |
250 | |
251 | Class method that allows a thread to detach itself. |
252 | |
fcea4b7c |
253 | =item threads->self() |
47ba8780 |
254 | |
fcea4b7c |
255 | Class method that allows a thread to obtain its own I<threads> object. |
47ba8780 |
256 | |
0f1612a7 |
257 | =item $thr->tid() |
258 | |
259 | Returns the ID of the thread. Thread IDs are unique integers with the main |
260 | thread in a program being 0, and incrementing by 1 for every thread created. |
47ba8780 |
261 | |
0f1612a7 |
262 | =item threads->tid() |
38875929 |
263 | |
0f1612a7 |
264 | Class method that allows a thread to obtain its own ID. |
47ba8780 |
265 | |
0f1612a7 |
266 | =item threads->object($tid) |
8c9849ff |
267 | |
0f1612a7 |
268 | This will return the I<threads> object for the I<active> thread associated |
269 | with the specified thread ID. Returns C<undef> if there is no thread |
270 | associated with the TID, if the thread is joined or detached, if no TID is |
271 | specified or if the specified TID is undef. |
8c9849ff |
272 | |
fcea4b7c |
273 | =item threads->yield() |
f9dff5f5 |
274 | |
38875929 |
275 | This is a suggestion to the OS to let this thread yield CPU time to other |
276 | threads. What actually happens is highly dependent upon the underlying |
277 | thread implementation. |
f9dff5f5 |
278 | |
fcea4b7c |
279 | You may do C<use threads qw(yield)>, and then just use C<yield()> in your |
70f2e746 |
280 | code. |
281 | |
f4cc38af |
282 | =item threads->list() |
678a9b6c |
283 | |
f4cc38af |
284 | In a list context, returns a list of all non-joined, non-detached I<threads> |
285 | objects. In a scalar context, returns a count of the same. |
678a9b6c |
286 | |
0f1612a7 |
287 | =item $thr1->equal($thr2) |
288 | |
289 | Tests if two threads objects are the same thread or not. This is overloaded |
fcea4b7c |
290 | to the more natural forms: |
0f1612a7 |
291 | |
292 | if ($thr1 == $thr2) { |
293 | print("Threads are the same\n"); |
294 | } |
fcea4b7c |
295 | # or |
296 | if ($thr1 != $thr2) { |
297 | print("Threads differ\n"); |
298 | } |
0f1612a7 |
299 | |
300 | (Thread comparison is based on thread IDs.) |
301 | |
386c44e5 |
302 | =item async BLOCK; |
303 | |
304 | C<async> creates a thread to execute the block immediately following |
fcea4b7c |
305 | it. This block is treated as an anonymous subroutine, and so must have a |
306 | semi-colon after the closing brace. Like C<threads->create()>, C<async> |
307 | returns a I<threads> object. |
386c44e5 |
308 | |
f4cc38af |
309 | =item $thr->_handle() |
310 | |
311 | This I<private> method returns the memory location of the internal thread |
fcea4b7c |
312 | structure associated with a threads object. For Win32, this is a pointer to |
313 | the C<HANDLE> value returned by C<CreateThread> (i.e., C<HANDLE *>); for other |
314 | platforms, it is a pointer to the C<pthread_t> structure used in the |
315 | C<pthread_create> call (i.e., C<pthread_t *>. |
f4cc38af |
316 | |
317 | This method is of no use for general Perl threads programming. Its intent is |
318 | to provide other (XS-based) thread modules with the capability to access, and |
319 | possibly manipulate, the underlying thread structure associated with a Perl |
320 | thread. |
321 | |
322 | =item threads->_handle() |
323 | |
324 | Class method that allows a thread to obtain its own I<handle>. |
325 | |
47ba8780 |
326 | =back |
327 | |
514612b7 |
328 | =head1 THREAD STACK SIZE |
329 | |
330 | The default per-thread stack size for different platforms varies |
331 | significantly, and is almost always far more than is needed for most |
332 | applications. On Win32, Perl's makefile explicitly sets the default stack to |
333 | 16 MB; on most other platforms, the system default is used, which again may be |
334 | much larger than is needed. |
335 | |
336 | By tuning the stack size to more accurately reflect your application's needs, |
337 | you may significantly reduce your application's memory usage, and increase the |
338 | number of simultaneously running threads. |
339 | |
340 | N.B., on Windows, Address space allocation granularity is 64 KB, therefore, |
341 | setting the stack smaller than that on Win32 Perl will not save any more |
342 | memory. |
343 | |
344 | =over |
345 | |
346 | =item threads->get_stack_size(); |
347 | |
348 | Returns the current default per-thread stack size. The default is zero, which |
349 | means the system default stack size is currently in use. |
350 | |
351 | =item $size = $thr->get_stack_size(); |
352 | |
353 | Returns the stack size for a particular thread. A return value of zero |
354 | indicates the system default stack size was used for the thread. |
355 | |
356 | =item $old_size = threads->set_stack_size($new_size); |
357 | |
358 | Sets a new default per-thread stack size, and returns the previous setting. |
359 | |
360 | Some platforms have a minimum thread stack size. Trying to set the stack size |
361 | below this value will result in a warning, and the minimum stack size will be |
362 | used. |
363 | |
364 | Some Linux platforms have a maximum stack size. Setting too large of a stack |
365 | size will cause thread creation to fail. |
366 | |
367 | If needed, C<$new_size> will be rounded up to the next multiple of the memory |
368 | page size (usually 4096 or 8192). |
369 | |
370 | Threads created after the stack size is set will then either call |
371 | C<pthread_attr_setstacksize()> I<(for pthreads platforms)>, or supply the |
372 | stack size to C<CreateThread()> I<(for Win32 Perl)>. |
373 | |
374 | (Obviously, this call does not affect any currently extant threads.) |
375 | |
376 | =item use threads ('stack_size' => VALUE); |
377 | |
378 | This sets the default per-thread stack size at the start of the application. |
379 | |
380 | =item $ENV{'PERL5_ITHREADS_STACK_SIZE'} |
381 | |
382 | The default per-thread stack size may be set at the start of the application |
383 | through the use of the environment variable C<PERL5_ITHREADS_STACK_SIZE>: |
384 | |
385 | PERL5_ITHREADS_STACK_SIZE=1048576 |
386 | export PERL5_ITHREADS_STACK_SIZE |
387 | perl -e'use threads; print(threads->get_stack_size(), "\n")' |
388 | |
389 | This value overrides any C<stack_size> parameter given to C<use threads>. Its |
390 | primary purpose is to permit setting the per-thread stack size for legacy |
391 | threaded applications. |
392 | |
393 | =item threads->create({'stack_size' => VALUE}, FUNCTION, ARGS) |
394 | |
395 | This change to the thread creation method permits specifying the stack size |
396 | for an individual thread. |
397 | |
398 | =item $thr2 = $thr1->create(FUNCTION, ARGS) |
399 | |
400 | This creates a new thread (C<$thr2>) that inherits the stack size from an |
401 | existing thread (C<$thr1>). This is shorthand for the following: |
402 | |
403 | my $stack_size = $thr1->get_stack_size(); |
404 | my $thr2 = threads->create({'stack_size' => $stack_size}, FUNCTION, ARGS); |
405 | |
406 | =back |
407 | |
e4f9f4fe |
408 | =head1 WARNINGS |
409 | |
410 | =over 4 |
411 | |
fcea4b7c |
412 | =item A thread exited while # other threads were still running |
e4f9f4fe |
413 | |
fc04eb16 |
414 | A thread (not necessarily the main thread) exited while there were still other |
415 | threads running. Usually, it's a good idea to first collect the return values |
416 | of the created threads by joining them, and only then exit from the main |
417 | thread. |
e4f9f4fe |
418 | |
514612b7 |
419 | =item Using minimum thread stack size of # |
420 | |
421 | Some platforms have a minimum thread stack size. Trying to set the stack size |
422 | below this value will result in the above warning, and the stack size will be |
423 | set to the minimum. |
424 | |
e4f9f4fe |
425 | =back |
47ba8780 |
426 | |
0f1612a7 |
427 | =head1 ERRORS |
428 | |
429 | =over 4 |
430 | |
fcea4b7c |
431 | =item This Perl not built to support threads |
678a9b6c |
432 | |
0f1612a7 |
433 | The particular copy of Perl that you're trying to use was not built using the |
434 | C<useithreads> configuration option. |
678a9b6c |
435 | |
0f1612a7 |
436 | Having threads support requires all of Perl and all of the XS modules in the |
437 | Perl installation to be rebuilt; it is not just a question of adding the |
438 | L<threads> module (i.e., threaded and non-threaded Perls are binary |
439 | incompatible.) |
440 | |
514612b7 |
441 | =item Cannot change stack size of an existing thread |
442 | |
443 | The stack size of currently extant threads cannot be changed, therefore, the |
444 | following results in the above error: |
445 | |
446 | $thr->set_stack_size($size); |
447 | |
448 | =item Thread creation failed: pthread_attr_setstacksize(I<SIZE>) returned 22 |
449 | |
450 | The specified I<SIZE> exceeds the system's maximum stack size. Use a smaller |
451 | value for the stack size. |
452 | |
0f1612a7 |
453 | =back |
47ba8780 |
454 | |
ab80e3f2 |
455 | =head1 BUGS |
456 | |
47ba8780 |
457 | =over |
458 | |
fcea4b7c |
459 | =item Parent-child threads |
678a9b6c |
460 | |
fcea4b7c |
461 | On some platforms, it might not be possible to destroy I<parent> threads while |
462 | there are still existing I<child> threads. |
678a9b6c |
463 | |
88f8c1df |
464 | =item Creating threads inside BEGIN blocks |
465 | |
fc04eb16 |
466 | Creating threads inside BEGIN blocks (or during the compilation phase in |
467 | general) does not work. (In Windows, trying to use fork() inside BEGIN blocks |
468 | is an equally losing proposition, since it has been implemented in very much |
469 | the same way as threads.) |
88f8c1df |
470 | |
678a9b6c |
471 | =item PERL_OLD_SIGNALS are not threadsafe, will not be. |
47ba8780 |
472 | |
fc04eb16 |
473 | If your Perl has been built with PERL_OLD_SIGNALS (one has to explicitly add |
474 | that symbol to I<ccflags>, see C<perl -V>), signal handling is not threadsafe. |
88f8c1df |
475 | |
0f1612a7 |
476 | =item Returning closures from threads |
477 | |
478 | Returning a closure from a thread does not work, usually crashing Perl in the |
479 | process. |
480 | |
481 | =item Perl Bugs and the CPAN Version of L<threads> |
482 | |
483 | Support for threads extents beyond the code in this module (i.e., |
484 | F<threads.pm> and F<threads.xs>), and into the Perl iterpreter itself. Older |
485 | versions of Perl contain bugs that may manifest themselves despite using the |
486 | latest version of L<threads> from CPAN. There is no workaround for this other |
487 | than upgrading to the lastest version of Perl. |
488 | |
489 | (Before you consider posting a bug report, please consult, and possibly post a |
490 | message to the discussion forum to see if what you've encountered is a known |
491 | problem.) |
492 | |
47ba8780 |
493 | =back |
494 | |
0f1612a7 |
495 | =head1 REQUIREMENTS |
47ba8780 |
496 | |
0f1612a7 |
497 | Perl 5.8.0 or later |
47ba8780 |
498 | |
0f1612a7 |
499 | =head1 SEE ALSO |
47ba8780 |
500 | |
0f1612a7 |
501 | L<threads> Discussion Forum on CPAN: |
502 | L<http://www.cpanforum.com/dist/threads> |
47ba8780 |
503 | |
0f1612a7 |
504 | Annotated POD for L<threads>: |
d305c2c9 |
505 | L<http://annocpan.org/~JDHEDDEN/threads-1.26/shared.pm> |
47ba8780 |
506 | |
0f1612a7 |
507 | L<threads::shared>, L<perlthrtut> |
47ba8780 |
508 | |
0f1612a7 |
509 | L<http://www.perl.com/pub/a/2002/06/11/threads.html> and |
510 | L<http://www.perl.com/pub/a/2002/09/04/threads.html> |
47ba8780 |
511 | |
0f1612a7 |
512 | Perl threads mailing list: |
513 | L<http://lists.cpan.org/showlist.cgi?name=iThreads> |
47ba8780 |
514 | |
514612b7 |
515 | Stack size discussion: |
516 | L<http://www.perlmonks.org/?node_id=532956> |
517 | |
0f1612a7 |
518 | =head1 AUTHOR |
47ba8780 |
519 | |
0f1612a7 |
520 | Artur Bergman E<lt>sky AT crucially DOT netE<gt> |
521 | |
522 | threads is released under the same license as Perl. |
523 | |
524 | CPAN version produced by Jerry D. Hedden <jdhedden AT cpan DOT org> |
525 | |
526 | =head1 ACKNOWLEDGEMENTS |
527 | |
528 | Richard Soderberg E<lt>perl AT crystalflame DOT netE<gt> - |
529 | Helping me out tons, trying to find reasons for races and other weird bugs! |
530 | |
531 | Simon Cozens E<lt>simon AT brecon DOT co DOT ukE<gt> - |
532 | Being there to answer zillions of annoying questions |
533 | |
534 | Rocco Caputo E<lt>troc AT netrus DOT netE<gt> |
47ba8780 |
535 | |
0f1612a7 |
536 | Vipul Ved Prakash E<lt>mail AT vipul DOT netE<gt> - |
537 | Helping with debugging |
47ba8780 |
538 | |
514612b7 |
539 | Dean Arnold E<lt>darnold AT presicient DOT comE<gt> - |
540 | Stack size API |
541 | |
47ba8780 |
542 | =cut |