8 our $VERSION = '1.24_02';
9 my $XS_VERSION = $VERSION;
10 $VERSION = eval $VERSION;
14 # Verify this Perl supports threads
16 if (! $Config{useithreads}) {
17 die("This Perl not built to support threads\n");
20 # Declare that we have been loaded
21 $threads::threads = 1;
23 # Complain if 'threads' is loaded after 'threads::shared'
24 if ($threads::shared::threads_shared) {
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.
36 XSLoader::load('threads', $XS_VERSION);
43 my $class = shift; # Not used
45 # Exported subroutines
46 my @EXPORT = qw(async);
49 while (my $sym = shift) {
51 push(@EXPORT, qw(yield));
58 # Export subroutine names
59 my $caller = caller();
60 foreach my $sym (@EXPORT) {
62 *{$caller.'::'.$sym} = \&{$sym};
69 # 'new' is an alias for 'create'
72 # 'async' is a function alias for the 'threads->create()' method
75 unshift(@_, 'threads');
76 # Use "goto" trick to avoid pad problems from 5.8.1 (fixed in 5.8.2)
80 # Thread object equality checking
83 '!=' => sub { ! equal(@_) },
93 threads - Perl interpreter-based threads
97 This document describes threads version 1.24
101 use threads ('yield');
105 print "Thread started: @args\n";
107 my $thread = threads->create('start_thread', 'argument');
110 threads->create(sub { print("I am a thread\n"); })->join();
112 my $thread3 = async { foreach (@files) { ... } };
115 # Invoke thread in list context so it can return a list
116 my ($thr) = threads->create(sub { return (qw/a b c/); });
117 my @results = $thr->join();
121 $thread = threads->self();
122 $thread = threads->object($tid);
124 $tid = threads->tid();
125 $tid = threads->self->tid();
126 $tid = $thread->tid();
131 my @threads = threads->list();
132 my $thread_count = threads->list();
134 if ($thr1 == $thr2) {
140 Perl 5.6 introduced something called interpreter threads. Interpreter threads
141 are different from I<5005threads> (the thread model of Perl 5.005) by creating
142 a new Perl interpreter per thread, and not sharing any data or state between
145 Prior to Perl 5.8, this has only been available to people embedding Perl, and
146 for emulating fork() on Windows.
148 The I<threads> API is loosely based on the old Thread.pm API. It is very
149 important to note that variables are not shared between threads, all variables
150 are by default thread local. To use shared variables one must use
153 It is also important to note that you must enable threads by doing C<use
154 threads> as early as possible in the script itself, and that it is not
155 possible to enable threading inside an C<eval "">, C<do>, C<require>, or
156 C<use>. In particular, if you are intending to share variables with
157 L<threads::shared>, you must C<use threads> before you C<use threads::shared>.
158 (C<threads> will emit a warning if you do it the other way around.)
162 =item $thr = threads->create(FUNCTION, ARGS)
164 This will create a new thread that will begin execution with the specified
165 entry point function, and give it the I<ARGS> list as parameters. It will
166 return the corresponding threads object, or C<undef> if thread creation failed.
168 I<FUNCTION> may either be the name of a function, an anonymous subroutine, or
171 my $thr = threads->create('func_name', ...);
173 my $thr = threads->create(sub { ... }, ...);
175 my $thr = threads->create(\&func, ...);
177 The thread may be created in I<list> context, or I<scalar> context as follows:
179 # Create thread in list context
180 my ($thr) = threads->create(...);
182 # Create thread in scalar context
183 my $thr = threads->create(...);
185 This has consequences for the C<-E<gt>join()> method describe below.
187 Although a thread may be created in I<void> context, to do so you must
188 I<chain> either the C<-E<gt>join()> or C<-E<gt>detach()> method to the
189 C<-E<gt>create()> call:
191 threads->create(...)->join();
193 The C<-E<gt>new()> method is an alias for C<-E<gt>create()>.
197 This will wait for the corresponding thread to complete its execution. When
198 the thread finishes, C<-E<gt>join()> will return the return value(s) of the
199 entry point function.
201 The context (void, scalar or list) of the thread creation is also the
202 context for C<-E<gt>join()>. This means that if you intend to return an array
203 from a thread, you must use C<my ($thr) = threads->create(...)>, and that
204 if you intend to return a scalar, you must use C<my $thr = ...>:
206 # Create thread in list context
207 my ($thr1) = threads->create(sub {
208 my @results = qw(a b c);
211 # Retrieve list results from thread
212 my @res1 = $thr1->join();
214 # Create thread in scalar context
215 my $thr2 = threads->create(sub {
219 # Retrieve scalar result from thread
220 my $res2 = $thr2->join();
222 If the program exits without all other threads having been either joined or
223 detached, then a warning will be issued. (A program exits either because one
224 of its threads explicitly calls L<exit()|perlfunc/"exit EXPR">, or in the case
225 of the main thread, reaches the end of the main program file.)
227 Calling C<-E<gt>join()> or C<-E<gt>detach()> on an already joined thread will
228 cause an error to be thrown.
232 Makes the thread unjoinable, and causes any eventual return value to be
235 Calling C<-E<gt>join()> or C<-E<gt>detach()> on an already detached thread
236 will cause an error to be thrown.
238 =item threads->detach()
240 Class method that allows a thread to detach itself.
242 =item threads->self()
244 Class method that allows a thread to obtain its own I<threads> object.
248 Returns the ID of the thread. Thread IDs are unique integers with the main
249 thread in a program being 0, and incrementing by 1 for every thread created.
253 Class method that allows a thread to obtain its own ID.
255 =item threads->object($tid)
257 This will return the I<threads> object for the I<active> thread associated
258 with the specified thread ID. Returns C<undef> if there is no thread
259 associated with the TID, if the thread is joined or detached, if no TID is
260 specified or if the specified TID is undef.
262 =item threads->yield()
264 This is a suggestion to the OS to let this thread yield CPU time to other
265 threads. What actually happens is highly dependent upon the underlying
266 thread implementation.
268 You may do C<use threads qw(yield)>, and then just use C<yield()> in your
271 =item threads->list()
273 In a list context, returns a list of all non-joined, non-detached I<threads>
274 objects. In a scalar context, returns a count of the same.
276 =item $thr1->equal($thr2)
278 Tests if two threads objects are the same thread or not. This is overloaded
279 to the more natural forms:
281 if ($thr1 == $thr2) {
282 print("Threads are the same\n");
285 if ($thr1 != $thr2) {
286 print("Threads differ\n");
289 (Thread comparison is based on thread IDs.)
293 C<async> creates a thread to execute the block immediately following
294 it. This block is treated as an anonymous subroutine, and so must have a
295 semi-colon after the closing brace. Like C<threads->create()>, C<async>
296 returns a I<threads> object.
298 =item $thr->_handle()
300 This I<private> method returns the memory location of the internal thread
301 structure associated with a threads object. For Win32, this is a pointer to
302 the C<HANDLE> value returned by C<CreateThread> (i.e., C<HANDLE *>); for other
303 platforms, it is a pointer to the C<pthread_t> structure used in the
304 C<pthread_create> call (i.e., C<pthread_t *>.
306 This method is of no use for general Perl threads programming. Its intent is
307 to provide other (XS-based) thread modules with the capability to access, and
308 possibly manipulate, the underlying thread structure associated with a Perl
311 =item threads->_handle()
313 Class method that allows a thread to obtain its own I<handle>.
321 =item A thread exited while # other threads were still running
323 A thread (not necessarily the main thread) exited while there were still other
324 threads running. Usually, it's a good idea to first collect the return values
325 of the created threads by joining them, and only then exit from the main
334 =item This Perl not built to support threads
336 The particular copy of Perl that you're trying to use was not built using the
337 C<useithreads> configuration option.
339 Having threads support requires all of Perl and all of the XS modules in the
340 Perl installation to be rebuilt; it is not just a question of adding the
341 L<threads> module (i.e., threaded and non-threaded Perls are binary
350 =item Parent-child threads
352 On some platforms, it might not be possible to destroy I<parent> threads while
353 there are still existing I<child> threads.
355 =item Creating threads inside BEGIN blocks
357 Creating threads inside BEGIN blocks (or during the compilation phase in
358 general) does not work. (In Windows, trying to use fork() inside BEGIN blocks
359 is an equally losing proposition, since it has been implemented in very much
360 the same way as threads.)
362 =item PERL_OLD_SIGNALS are not threadsafe, will not be.
364 If your Perl has been built with PERL_OLD_SIGNALS (one has to explicitly add
365 that symbol to I<ccflags>, see C<perl -V>), signal handling is not threadsafe.
367 =item Returning closures from threads
369 Returning a closure from a thread does not work, usually crashing Perl in the
372 =item Perl Bugs and the CPAN Version of L<threads>
374 Support for threads extents beyond the code in this module (i.e.,
375 F<threads.pm> and F<threads.xs>), and into the Perl iterpreter itself. Older
376 versions of Perl contain bugs that may manifest themselves despite using the
377 latest version of L<threads> from CPAN. There is no workaround for this other
378 than upgrading to the lastest version of Perl.
380 (Before you consider posting a bug report, please consult, and possibly post a
381 message to the discussion forum to see if what you've encountered is a known
392 L<threads> Discussion Forum on CPAN:
393 L<http://www.cpanforum.com/dist/threads>
395 Annotated POD for L<threads>:
396 L<http://annocpan.org/~JDHEDDEN/threads-1.24/shared.pm>
398 L<threads::shared>, L<perlthrtut>
400 L<http://www.perl.com/pub/a/2002/06/11/threads.html> and
401 L<http://www.perl.com/pub/a/2002/09/04/threads.html>
403 Perl threads mailing list:
404 L<http://lists.cpan.org/showlist.cgi?name=iThreads>
408 Artur Bergman E<lt>sky AT crucially DOT netE<gt>
410 threads is released under the same license as Perl.
412 CPAN version produced by Jerry D. Hedden <jdhedden AT cpan DOT org>
414 =head1 ACKNOWLEDGEMENTS
416 Richard Soderberg E<lt>perl AT crystalflame DOT netE<gt> -
417 Helping me out tons, trying to find reasons for races and other weird bugs!
419 Simon Cozens E<lt>simon AT brecon DOT co DOT ukE<gt> -
420 Being there to answer zillions of annoying questions
422 Rocco Caputo E<lt>troc AT netrus DOT netE<gt>
424 Vipul Ved Prakash E<lt>mail AT vipul DOT netE<gt> -
425 Helping with debugging