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