This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
threads - stack size support
[perl5.git] / ext / threads / threads.pm
1 package threads;
2
3 use 5.008;
4
5 use strict;
6 use warnings;
7
8 our $VERSION = '1.25';
9 my $XS_VERSION = $VERSION;
10 $VERSION = eval $VERSION;
11
12
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");
18     }
19
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    }
31 }
32
33
34 # Load the XS code
35 require XSLoader;
36 XSLoader::load('threads', $XS_VERSION);
37
38
39 ### Export ###
40
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) {
50         if ($sym =~ /^stack/) {
51             threads->set_stack_size(shift);
52
53         } elsif ($sym =~ /all/) {
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     }
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     }
72 }
73
74
75 ### Methods, etc. ###
76
77 # 'new' is an alias for 'create'
78 *new = \&create;
79
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
95 1;
96
97 __END__
98
99 =head1 NAME
100
101 threads - Perl interpreter-based threads
102
103 =head1 VERSION
104
105 This document describes threads version 1.25
106
107 =head1 SYNOPSIS
108
109     use threads ('yield', 'stack_size' => 64*4096);
110
111     sub start_thread {
112         my @args = @_;
113         print "Thread started: @args\n";
114     }
115     my $thread = threads->create('start_thread', 'argument');
116     $thread->join();
117
118     threads->create(sub { print("I am a thread\n"); })->join();
119
120     my $thread3 = async { foreach (@files) { ... } };
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();
126
127     $thread->detach();
128
129     $thread = threads->self();
130     $thread = threads->object($tid);
131
132     $tid = threads->tid();
133     $tid = threads->self->tid();
134     $tid = $thread->tid();
135
136     threads->yield();
137     yield();
138
139     my @threads = threads->list();
140     my $thread_count = threads->list();
141
142     if ($thr1 == $thr2) {
143         ...
144     }
145
146     $stack_size = threads->get_stack_size();
147     $old_size = threads->set_stack_size(32*4096);
148
149 =head1 DESCRIPTION
150
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.
155
156 Prior to Perl 5.8, this has only been available to people embedding Perl, and
157 for emulating fork() on Windows.
158
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>.
163
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.)
170
171 =over
172
173 =item $thr = threads->create(FUNCTION, ARGS)
174
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.
178
179 I<FUNCTION> may either be the name of a function, an anonymous subroutine, or
180 a code ref.
181
182     my $thr = threads->create('func_name', ...);
183         # or
184     my $thr = threads->create(sub { ... }, ...);
185         # or
186     my $thr = threads->create(\&func, ...);
187
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:
201
202     threads->create(...)->join();
203
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.)
237
238 Calling C<-E<gt>join()> or C<-E<gt>detach()> on an already joined thread will
239 cause an error to be thrown.
240
241 =item $thr->detach()
242
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.
248
249 =item threads->detach()
250
251 Class method that allows a thread to detach itself.
252
253 =item threads->self()
254
255 Class method that allows a thread to obtain its own I<threads> object.
256
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.
261
262 =item threads->tid()
263
264 Class method that allows a thread to obtain its own ID.
265
266 =item threads->object($tid)
267
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.
272
273 =item threads->yield()
274
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.
278
279 You may do C<use threads qw(yield)>, and then just use C<yield()> in your
280 code.
281
282 =item threads->list()
283
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.
286
287 =item $thr1->equal($thr2)
288
289 Tests if two threads objects are the same thread or not.  This is overloaded
290 to the more natural forms:
291
292     if ($thr1 == $thr2) {
293         print("Threads are the same\n");
294     }
295     # or
296     if ($thr1 != $thr2) {
297         print("Threads differ\n");
298     }
299
300 (Thread comparison is based on thread IDs.)
301
302 =item async BLOCK;
303
304 C<async> creates a thread to execute the block immediately following
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.
308
309 =item $thr->_handle()
310
311 This I<private> method returns the memory location of the internal thread
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 *>.
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
326 =back
327
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
408 =head1 WARNINGS
409
410 =over 4
411
412 =item A thread exited while # other threads were still running
413
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.
418
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
425 =back
426
427 =head1 ERRORS
428
429 =over 4
430
431 =item This Perl not built to support threads
432
433 The particular copy of Perl that you're trying to use was not built using the
434 C<useithreads> configuration option.
435
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
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
453 =back
454
455 =head1 BUGS
456
457 =over
458
459 =item Parent-child threads
460
461 On some platforms, it might not be possible to destroy I<parent> threads while
462 there are still existing I<child> threads.
463
464 =item Creating threads inside BEGIN blocks
465
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.)
470
471 =item PERL_OLD_SIGNALS are not threadsafe, will not be.
472
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.
475
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
493 =back
494
495 =head1 REQUIREMENTS
496
497 Perl 5.8.0 or later
498
499 =head1 SEE ALSO
500
501 L<threads> Discussion Forum on CPAN:
502 L<http://www.cpanforum.com/dist/threads>
503
504 Annotated POD for L<threads>:
505 L<http://annocpan.org/~JDHEDDEN/threads-1.25/shared.pm>
506
507 L<threads::shared>, L<perlthrtut>
508
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>
511
512 Perl threads mailing list:
513 L<http://lists.cpan.org/showlist.cgi?name=iThreads>
514
515 Stack size discussion:
516 L<http://www.perlmonks.org/?node_id=532956>
517
518 =head1 AUTHOR
519
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>
535
536 Vipul Ved Prakash E<lt>mail AT vipul DOT netE<gt> -
537 Helping with debugging
538
539 Dean Arnold E<lt>darnold AT presicient DOT comE<gt> -
540 Stack size API
541
542 =cut