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