ext/threads/threads.pm

   1 package threads;
   2
   3 use 5.008;
   4 use strict;
   5 use warnings;
   6 use Config;
   7
   8 BEGIN {
   9     unless ($Config{useithreads}) {
  10         my @caller = caller(2);
  11         die <<EOF;
  12 $caller[1] line $caller[2]:
  13
  14 This Perl hasn't been configured and built properly for the threads
  15 module to work.  (The 'useithreads' configuration option hasn't been used.)
  16
  17 Having threads support requires all of Perl and all of the XS modules in
  18 the Perl installation to be rebuilt, it is not just a question of adding
  19 the threads module.  (In other words, threaded and non-threaded Perls
  20 are binary incompatible.)
  21
  22 If you want to the use the threads module, please contact the people
  23 who built your Perl.
  24
  25 Cannot continue, aborting.
  26 EOF
  27     }
  28 }
  29
  30 use overload
  31     '==' => \&equal,
  32     'fallback' => 1;
  33
  34 BEGIN {
  35     warn "Warning, threads::shared has already been loaded. ".
  36        "To enable shared variables for these modules 'use threads' ".
  37        "must be called before any of those modules are loaded\n"
  38                if($threads::shared::threads_shared);
  39 }
  40
  41 our $VERSION = '1.17';
  42
  43
  44 # Load the XS code
  45 require XSLoader;
  46 XSLoader::load('threads', $VERSION);
  47
  48
  49 ### Export ###
  50
  51 sub import
  52 {
  53     my $class = shift;   # Not used
  54
  55     # Exported subroutines
  56     my @EXPORT = qw(async);
  57
  58     # Handle args
  59     while (my $sym = shift) {
  60         if ($sym =~ /all/) {
  61             push(@EXPORT, qw(yield));
  62
  63         } else {
  64             push(@EXPORT, $sym);
  65         }
  66     }
  67
  68     # Export subroutine names
  69     my $caller = caller();
  70     foreach my $sym (@EXPORT) {
  71         no strict 'refs';
  72         *{$caller.'::'.$sym} = \&{$sym};
  73     }
  74 }
  75
  76
  77 ### Methods, etc. ###
  78
  79 # || 0 to ensure compatibility with previous versions
  80 sub equal { ($_[0]->tid == $_[1]->tid) || 0 }
  81
  82 # use "goto" trick to avoid pad problems from 5.8.1 (fixed in 5.8.2)
  83 # should also be faster
  84 sub async (&;@) { unshift @_,'threads'; goto &new }
  85
  86 sub object {
  87     return undef unless @_ > 1;
  88     foreach (threads->list) {
  89         return $_ if $_->tid == $_[1];
  90     }
  91     return undef;
  92 }
  93
  94 $threads::threads = 1;
  95
  96 # why document 'new' then use 'create' in the tests!
  97 *create = \&new;
  98
  99 1;
 100
 101 __END__
 102
 103 =head1 NAME
 104
 105 threads - Perl interpreter-based threads
 106
 107 =head1 VERSION
 108
 109 This document describes threads version 1.17
 110
 111 =head1 SYNOPSIS
 112
 113     use threads ('yield');
 114
 115     sub start_thread {
 116         my @args = @_;
 117         print "Thread started: @args\n";
 118     }
 119     my $thread = threads->create('start_thread', 'argument');
 120     $thread->join();
 121
 122     threads->create(sub { print("I am a thread\n"); })->join();
 123
 124     my $thread3 = async { foreach (@files) { ... } };
 125     $thread3->join();
 126
 127     # Invoke thread in list context so it can return a list
 128     my ($thr) = threads->create(sub { return (qw/a b c/); });
 129     my @results = $thr->join();
 130
 131     $thread->detach();
 132
 133     $thread = threads->self();
 134     $thread = threads->object($tid);
 135
 136     $tid = threads->tid();
 137     $tid = threads->self->tid();
 138     $tid = $thread->tid();
 139
 140     threads->yield();
 141     yield();
 142
 143     my @threads = threads->list();
 144
 145     if ($thr1 == $thr2) {
 146         ...
 147     }
 148
 149 =head1 DESCRIPTION
 150
 151 Perl 5.6 introduced something called interpreter threads.  Interpreter
 152 threads are different from "5005threads" (the thread model of Perl
 153 5.005) by creating a new perl interpreter per thread and not sharing
 154 any data or state between threads by default.
 155
 156 Prior to perl 5.8 this has only been available to people embedding
 157 perl and for emulating fork() on windows.
 158
 159 The 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
 161 variables are per default thread local.  To use shared variables one
 162 must use threads::shared.
 163
 164 It is also important to note that you must enable threads by doing
 165 C<use threads> as early as possible in the script itself and that it
 166 is not possible to enable threading inside an C<eval "">, C<do>,
 167 C<require>, or C<use>.  In particular, if you are intending to share
 168 variables with threads::shared, you must C<use threads> before you
 169 C<use threads::shared> and C<threads> will emit a warning if you do
 170 it the other way around.
 171
 172 =over
 173
 174 =item $thr = threads->create(FUNCTION, ARGS)
 175
 176 This will create a new thread that will begin execution with the specified
 177 entry point function, and give it the I<ARGS> list as parameters.  It will
 178 return the corresponding threads object, or C<undef> if thread creation failed.
 179
 180 I<FUNCTION> may either be the name of a function, an anonymous subroutine, or
 181 a code ref.
 182
 183     my $thr = threads->create('func_name', ...);
 184         # or
 185     my $thr = threads->create(sub { ... }, ...);
 186         # or
 187     my $thr = threads->create(\&func, ...);
 188
 189 The thread may be created in I<list> context, or I<scalar> context as follows:
 190
 191     # Create thread in list context
 192     my ($thr) = threads->create(...);
 193
 194     # Create thread in scalar context
 195     my $thr = threads->create(...);
 196
 197 This has consequences for the C<-E<gt>join()> method describe below.
 198
 199 Although a thread may be created in I<void> context, to do so you must
 200 I<chain> either the C<-E<gt>join()> or C<-E<gt>detach()> method to the
 201 C<-E<gt>create()> call:
 202
 203     threads->create(...)->join();
 204
 205 The C<-E<gt>new()> method is an alias for C<-E<gt>create()>.
 206
 207 =item $thr->join()
 208
 209 This will wait for the corresponding thread to complete its execution.  When
 210 the thread finishes, C<-E<gt>join()> will return the return value(s) of the
 211 entry point function.
 212
 213 The context (void, scalar or list) of the thread creation is also the
 214 context for C<-E<gt>join()>.  This means that if you intend to return an array
 215 from a thread, you must use C<my ($thr) = threads->create(...)>, and that
 216 if you intend to return a scalar, you must use C<my $thr = ...>:
 217
 218     # Create thread in list context
 219     my ($thr1) = threads->create(sub {
 220                                     my @results = qw(a b c);
 221                                     return (@results);
 222                                  };
 223     # Retrieve list results from thread
 224     my @res1 = $thr1->join();
 225
 226     # Create thread in scalar context
 227     my $thr2 = threads->create(sub {
 228                                     my $result = 42;
 229                                     return ($result);
 230                                  };
 231     # Retrieve scalar result from thread
 232     my $res2 = $thr2->join();
 233
 234 If the program exits without all other threads having been either joined or
 235 detached, then a warning will be issued. (A program exits either because one
 236 of its threads explicitly calls L<exit()|perlfunc/"exit EXPR">, or in the case
 237 of the main thread, reaches the end of the main program file.)
 238
 239 =item $thread->detach
 240
 241 Will make the thread unjoinable, and cause any eventual return value
 242 to be discarded.
 243
 244 Calling C<-E<gt>join()> on a detached thread will cause an error to be thrown.
 245
 246 =item threads->detach()
 247
 248 Class method that allows a thread to detach itself.
 249
 250 =item threads->self
 251
 252 This will return the thread object for the current thread.
 253
 254 =item $thr->tid()
 255
 256 Returns the ID of the thread.  Thread IDs are unique integers with the main
 257 thread in a program being 0, and incrementing by 1 for every thread created.
 258
 259 =item threads->tid()
 260
 261 Class method that allows a thread to obtain its own ID.
 262
 263 =item threads->object($tid)
 264
 265 This will return the I<threads> object for the I<active> thread associated
 266 with the specified thread ID.  Returns C<undef> if there is no thread
 267 associated with the TID, if the thread is joined or detached, if no TID is
 268 specified or if the specified TID is undef.
 269
 270 =item threads->yield();
 271
 272 This is a suggestion to the OS to let this thread yield CPU time to other
 273 threads.  What actually happens is highly dependent upon the underlying
 274 thread implementation.
 275
 276 You may do C<use threads qw(yield)> then use just a bare C<yield> in your
 277 code.
 278
 279 =item threads->list();
 280
 281 This will return a list of all non joined, non detached threads.
 282
 283 =item $thr1->equal($thr2)
 284
 285 Tests if two threads objects are the same thread or not.  This is overloaded
 286 to the more natural form:
 287
 288     if ($thr1 == $thr2) {
 289         print("Threads are the same\n");
 290     }
 291
 292 (Thread comparison is based on thread IDs.)
 293
 294 =item async BLOCK;
 295
 296 C<async> creates a thread to execute the block immediately following
 297 it.  This block is treated as an anonymous sub, and so must have a
 298 semi-colon after the closing brace. Like C<< threads->new >>, C<async>
 299 returns a thread object.
 300
 301 =back
 302
 303 =head1 WARNINGS
 304
 305 =over 4
 306
 307 =item A thread exited while %d other threads were still running
 308
 309 A thread (not necessarily the main thread) exited while there were
 310 still other threads running.  Usually it's a good idea to first collect
 311 the return values of the created threads by joining them, and only then
 312 exit from the main thread.
 313
 314 =back
 315
 316 =head1 ERRORS
 317
 318 =over 4
 319
 320 =item This Perl hasn't been configured and built properly for the threads...
 321
 322 The particular copy of Perl that you're trying to use was not built using the
 323 C<useithreads> configuration option.
 324
 325 Having threads support requires all of Perl and all of the XS modules in the
 326 Perl installation to be rebuilt; it is not just a question of adding the
 327 L<threads> module (i.e., threaded and non-threaded Perls are binary
 328 incompatible.)
 329
 330 =back
 331
 332 =head1 BUGS
 333
 334 =over
 335
 336 =item Parent-Child threads.
 337
 338 On some platforms it might not be possible to destroy "parent"
 339 threads while there are still existing child "threads".
 340
 341 =item tid is I32
 342
 343 The thread id is a 32 bit integer, it can potentially overflow.
 344 This might be fixed in a later version of perl.
 345
 346 =item Creating threads inside BEGIN blocks
 347
 348 Creating threads inside BEGIN blocks (or during the compilation phase
 349 in general) does not work.  (In Windows, trying to use fork() inside
 350 BEGIN blocks is an equally losing proposition, since it has been
 351 implemented in very much the same way as threads.)
 352
 353 =item PERL_OLD_SIGNALS are not threadsafe, will not be.
 354
 355 If your Perl has been built with PERL_OLD_SIGNALS (one has
 356 to explicitly add that symbol to ccflags, see C<perl -V>),
 357 signal handling is not threadsafe.
 358
 359 =item Returning closures from threads
 360
 361 Returning a closure from a thread does not work, usually crashing Perl in the
 362 process.
 363
 364 =item Perl Bugs and the CPAN Version of L<threads>
 365
 366 Support for threads extents beyond the code in this module (i.e.,
 367 F<threads.pm> and F<threads.xs>), and into the Perl iterpreter itself.  Older
 368 versions of Perl contain bugs that may manifest themselves despite using the
 369 latest version of L<threads> from CPAN.  There is no workaround for this other
 370 than upgrading to the lastest version of Perl.
 371
 372 (Before you consider posting a bug report, please consult, and possibly post a
 373 message to the discussion forum to see if what you've encountered is a known
 374 problem.)
 375
 376 =back
 377
 378 =head1 REQUIREMENTS
 379
 380 Perl 5.8.0 or later
 381
 382 =head1 SEE ALSO
 383
 384 L<threads> Discussion Forum on CPAN:
 385 L<http://www.cpanforum.com/dist/threads>
 386
 387 Annotated POD for L<threads>:
 388 L<http://annocpan.org/~JDHEDDEN/threads-1.17/shared.pm>
 389
 390 L<threads::shared>, L<perlthrtut>
 391
 392 L<http://www.perl.com/pub/a/2002/06/11/threads.html> and
 393 L<http://www.perl.com/pub/a/2002/09/04/threads.html>
 394
 395 Perl threads mailing list:
 396 L<http://lists.cpan.org/showlist.cgi?name=iThreads>
 397
 398 =head1 AUTHOR
 399
 400 Artur Bergman E<lt>sky AT crucially DOT netE<gt>
 401
 402 threads is released under the same license as Perl.
 403
 404 CPAN version produced by Jerry D. Hedden <jdhedden AT cpan DOT org>
 405
 406 =head1 ACKNOWLEDGEMENTS
 407
 408 Richard Soderberg E<lt>perl AT crystalflame DOT netE<gt> -
 409 Helping me out tons, trying to find reasons for races and other weird bugs!
 410
 411 Simon Cozens E<lt>simon AT brecon DOT co DOT ukE<gt> -
 412 Being there to answer zillions of annoying questions
 413
 414 Rocco Caputo E<lt>troc AT netrus DOT netE<gt>
 415
 416 Vipul Ved Prakash E<lt>mail AT vipul DOT netE<gt> -
 417 Helping with debugging
 418
 419 =cut