This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
fc62b9034d625812951ccdfa1a89bbcbe333d67c
[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.24_02';
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 =~ /all/) {
51             push(@EXPORT, qw(yield));
52
53         } else {
54             push(@EXPORT, $sym);
55         }
56     }
57
58     # Export subroutine names
59     my $caller = caller();
60     foreach my $sym (@EXPORT) {
61         no strict 'refs';
62         *{$caller.'::'.$sym} = \&{$sym};
63     }
64 }
65
66
67 ### Methods, etc. ###
68
69 # 'new' is an alias for 'create'
70 *new = \&create;
71
72 # 'async' is a function alias for the 'threads->create()' method
73 sub async (&;@)
74 {
75     unshift(@_, 'threads');
76     # Use "goto" trick to avoid pad problems from 5.8.1 (fixed in 5.8.2)
77     goto &create;
78 }
79
80 # Thread object equality checking
81 use overload (
82     '==' => \&equal,
83     '!=' => sub { ! equal(@_) },
84     'fallback' => 1
85 );
86
87 1;
88
89 __END__
90
91 =head1 NAME
92
93 threads - Perl interpreter-based threads
94
95 =head1 VERSION
96
97 This document describes threads version 1.24
98
99 =head1 SYNOPSIS
100
101     use threads ('yield');
102
103     sub start_thread {
104         my @args = @_;
105         print "Thread started: @args\n";
106     }
107     my $thread = threads->create('start_thread', 'argument');
108     $thread->join();
109
110     threads->create(sub { print("I am a thread\n"); })->join();
111
112     my $thread3 = async { foreach (@files) { ... } };
113     $thread3->join();
114
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();
118
119     $thread->detach();
120
121     $thread = threads->self();
122     $thread = threads->object($tid);
123
124     $tid = threads->tid();
125     $tid = threads->self->tid();
126     $tid = $thread->tid();
127
128     threads->yield();
129     yield();
130
131     my @threads = threads->list();
132     my $thread_count = threads->list();
133
134     if ($thr1 == $thr2) {
135         ...
136     }
137
138 =head1 DESCRIPTION
139
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
143 threads by default.
144
145 Prior to Perl 5.8, this has only been available to people embedding Perl, and
146 for emulating fork() on Windows.
147
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
151 L<threads::shared>.
152
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.)
159
160 =over
161
162 =item $thr = threads->create(FUNCTION, ARGS)
163
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.
167
168 I<FUNCTION> may either be the name of a function, an anonymous subroutine, or
169 a code ref.
170
171     my $thr = threads->create('func_name', ...);
172         # or
173     my $thr = threads->create(sub { ... }, ...);
174         # or
175     my $thr = threads->create(\&func, ...);
176
177 The thread may be created in I<list> context, or I<scalar> context as follows:
178
179     # Create thread in list context
180     my ($thr) = threads->create(...);
181
182     # Create thread in scalar context
183     my $thr = threads->create(...);
184
185 This has consequences for the C<-E<gt>join()> method describe below.
186
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:
190
191     threads->create(...)->join();
192
193 The C<-E<gt>new()> method is an alias for C<-E<gt>create()>.
194
195 =item $thr->join()
196
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.
200
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 = ...>:
205
206     # Create thread in list context
207     my ($thr1) = threads->create(sub {
208                                     my @results = qw(a b c);
209                                     return (@results);
210                                  };
211     # Retrieve list results from thread
212     my @res1 = $thr1->join();
213
214     # Create thread in scalar context
215     my $thr2 = threads->create(sub {
216                                     my $result = 42;
217                                     return ($result);
218                                  };
219     # Retrieve scalar result from thread
220     my $res2 = $thr2->join();
221
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.)
226
227 Calling C<-E<gt>join()> or C<-E<gt>detach()> on an already joined thread will
228 cause an error to be thrown.
229
230 =item $thr->detach()
231
232 Makes the thread unjoinable, and causes any eventual return value to be
233 discarded.
234
235 Calling C<-E<gt>join()> or C<-E<gt>detach()> on an already detached thread
236 will cause an error to be thrown.
237
238 =item threads->detach()
239
240 Class method that allows a thread to detach itself.
241
242 =item threads->self()
243
244 Class method that allows a thread to obtain its own I<threads> object.
245
246 =item $thr->tid()
247
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.
250
251 =item threads->tid()
252
253 Class method that allows a thread to obtain its own ID.
254
255 =item threads->object($tid)
256
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.
261
262 =item threads->yield()
263
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.
267
268 You may do C<use threads qw(yield)>, and then just use C<yield()> in your
269 code.
270
271 =item threads->list()
272
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.
275
276 =item $thr1->equal($thr2)
277
278 Tests if two threads objects are the same thread or not.  This is overloaded
279 to the more natural forms:
280
281     if ($thr1 == $thr2) {
282         print("Threads are the same\n");
283     }
284     # or
285     if ($thr1 != $thr2) {
286         print("Threads differ\n");
287     }
288
289 (Thread comparison is based on thread IDs.)
290
291 =item async BLOCK;
292
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.
297
298 =item $thr->_handle()
299
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 *>.
305
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
309 thread.
310
311 =item threads->_handle()
312
313 Class method that allows a thread to obtain its own I<handle>.
314
315 =back
316
317 =head1 WARNINGS
318
319 =over 4
320
321 =item A thread exited while # other threads were still running
322
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
326 thread.
327
328 =back
329
330 =head1 ERRORS
331
332 =over 4
333
334 =item This Perl not built to support threads
335
336 The particular copy of Perl that you're trying to use was not built using the
337 C<useithreads> configuration option.
338
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
342 incompatible.)
343
344 =back
345
346 =head1 BUGS
347
348 =over
349
350 =item Parent-child threads
351
352 On some platforms, it might not be possible to destroy I<parent> threads while
353 there are still existing I<child> threads.
354
355 =item Creating threads inside BEGIN blocks
356
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.)
361
362 =item PERL_OLD_SIGNALS are not threadsafe, will not be.
363
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.
366
367 =item Returning closures from threads
368
369 Returning a closure from a thread does not work, usually crashing Perl in the
370 process.
371
372 =item Perl Bugs and the CPAN Version of L<threads>
373
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.
379
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
382 problem.)
383
384 =back
385
386 =head1 REQUIREMENTS
387
388 Perl 5.8.0 or later
389
390 =head1 SEE ALSO
391
392 L<threads> Discussion Forum on CPAN:
393 L<http://www.cpanforum.com/dist/threads>
394
395 Annotated POD for L<threads>:
396 L<http://annocpan.org/~JDHEDDEN/threads-1.24/shared.pm>
397
398 L<threads::shared>, L<perlthrtut>
399
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>
402
403 Perl threads mailing list:
404 L<http://lists.cpan.org/showlist.cgi?name=iThreads>
405
406 =head1 AUTHOR
407
408 Artur Bergman E<lt>sky AT crucially DOT netE<gt>
409
410 threads is released under the same license as Perl.
411
412 CPAN version produced by Jerry D. Hedden <jdhedden AT cpan DOT org>
413
414 =head1 ACKNOWLEDGEMENTS
415
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!
418
419 Simon Cozens E<lt>simon AT brecon DOT co DOT ukE<gt> -
420 Being there to answer zillions of annoying questions
421
422 Rocco Caputo E<lt>troc AT netrus DOT netE<gt>
423
424 Vipul Ved Prakash E<lt>mail AT vipul DOT netE<gt> -
425 Helping with debugging
426
427 =cut