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