ext/threads/threads.pm

   1 package threads;
   2
   3 use 5.008;
   4
   5 use strict;
   6 use warnings;
   7
   8 our $VERSION = '1.25';
   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 =~ /^stack/) {
  51             threads->set_stack_size(shift);
  52
  53         } elsif ($sym =~ /all/) {
  54             push(@EXPORT, qw(yield));
  55
  56         } else {
  57             push(@EXPORT, $sym);
  58         }
  59     }
  60
  61     # Export subroutine names
  62     my $caller = caller();
  63     foreach my $sym (@EXPORT) {
  64         no strict 'refs';
  65         *{$caller.'::'.$sym} = \&{$sym};
  66     }
  67
  68     # Set stack size via environment variable
  69     if (exists($ENV{'PERL5_ITHREADS_STACK_SIZE'})) {
  70         threads->set_stack_size($ENV{'PERL5_ITHREADS_STACK_SIZE'});
  71     }
  72 }
  73
  74
  75 ### Methods, etc. ###
  76
  77 # 'new' is an alias for 'create'
  78 *new = \&create;
  79
  80 # 'async' is a function alias for the 'threads->create()' method
  81 sub async (&;@)
  82 {
  83     unshift(@_, 'threads');
  84     # Use "goto" trick to avoid pad problems from 5.8.1 (fixed in 5.8.2)
  85     goto &create;
  86 }
  87
  88 # Thread object equality checking
  89 use overload (
  90     '==' => \&equal,
  91     '!=' => sub { ! equal(@_) },
  92     'fallback' => 1
  93 );
  94
  95 1;
  96
  97 __END__
  98
  99 =head1 NAME
 100
 101 threads - Perl interpreter-based threads
 102
 103 =head1 VERSION
 104
 105 This document describes threads version 1.25
 106
 107 =head1 SYNOPSIS
 108
 109     use threads ('yield', 'stack_size' => 64*4096);
 110
 111     sub start_thread {
 112         my @args = @_;
 113         print "Thread started: @args\n";
 114     }
 115     my $thread = threads->create('start_thread', 'argument');
 116     $thread->join();
 117
 118     threads->create(sub { print("I am a thread\n"); })->join();
 119
 120     my $thread3 = async { foreach (@files) { ... } };
 121     $thread3->join();
 122
 123     # Invoke thread in list context so it can return a list
 124     my ($thr) = threads->create(sub { return (qw/a b c/); });
 125     my @results = $thr->join();
 126
 127     $thread->detach();
 128
 129     $thread = threads->self();
 130     $thread = threads->object($tid);
 131
 132     $tid = threads->tid();
 133     $tid = threads->self->tid();
 134     $tid = $thread->tid();
 135
 136     threads->yield();
 137     yield();
 138
 139     my @threads = threads->list();
 140     my $thread_count = threads->list();
 141
 142     if ($thr1 == $thr2) {
 143         ...
 144     }
 145
 146     $stack_size = threads->get_stack_size();
 147     $old_size = threads->set_stack_size(32*4096);
 148
 149 =head1 DESCRIPTION
 150
 151 Perl 5.6 introduced something called interpreter threads.  Interpreter threads
 152 are different from I<5005threads> (the thread model of Perl 5.005) by creating
 153 a new Perl interpreter per thread, and not sharing any data or state between
 154 threads by default.
 155
 156 Prior to Perl 5.8, this has only been available to people embedding Perl, and
 157 for emulating fork() on Windows.
 158
 159 The I<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 variables
 161 are by default thread local.  To use shared variables one must use
 162 L<threads::shared>.
 163
 164 It is also important to note that you must enable threads by doing C<use
 165 threads> as early as possible in the script itself, and that it is not
 166 possible to enable threading inside an C<eval "">, C<do>, C<require>, or
 167 C<use>.  In particular, if you are intending to share variables with
 168 L<threads::shared>, you must C<use threads> before you C<use threads::shared>.
 169 (C<threads> will emit a warning if you do it the other way around.)
 170
 171 =over
 172
 173 =item $thr = threads->create(FUNCTION, ARGS)
 174
 175 This will create a new thread that will begin execution with the specified
 176 entry point function, and give it the I<ARGS> list as parameters.  It will
 177 return the corresponding threads object, or C<undef> if thread creation failed.
 178
 179 I<FUNCTION> may either be the name of a function, an anonymous subroutine, or
 180 a code ref.
 181
 182     my $thr = threads->create('func_name', ...);
 183         # or
 184     my $thr = threads->create(sub { ... }, ...);
 185         # or
 186     my $thr = threads->create(\&func, ...);
 187
 188 The thread may be created in I<list> context, or I<scalar> context as follows:
 189
 190     # Create thread in list context
 191     my ($thr) = threads->create(...);
 192
 193     # Create thread in scalar context
 194     my $thr = threads->create(...);
 195
 196 This has consequences for the C<-E<gt>join()> method describe below.
 197
 198 Although a thread may be created in I<void> context, to do so you must
 199 I<chain> either the C<-E<gt>join()> or C<-E<gt>detach()> method to the
 200 C<-E<gt>create()> call:
 201
 202     threads->create(...)->join();
 203
 204 The C<-E<gt>new()> method is an alias for C<-E<gt>create()>.
 205
 206 =item $thr->join()
 207
 208 This will wait for the corresponding thread to complete its execution.  When
 209 the thread finishes, C<-E<gt>join()> will return the return value(s) of the
 210 entry point function.
 211
 212 The context (void, scalar or list) of the thread creation is also the
 213 context for C<-E<gt>join()>.  This means that if you intend to return an array
 214 from a thread, you must use C<my ($thr) = threads->create(...)>, and that
 215 if you intend to return a scalar, you must use C<my $thr = ...>:
 216
 217     # Create thread in list context
 218     my ($thr1) = threads->create(sub {
 219                                     my @results = qw(a b c);
 220                                     return (@results);
 221                                  };
 222     # Retrieve list results from thread
 223     my @res1 = $thr1->join();
 224
 225     # Create thread in scalar context
 226     my $thr2 = threads->create(sub {
 227                                     my $result = 42;
 228                                     return ($result);
 229                                  };
 230     # Retrieve scalar result from thread
 231     my $res2 = $thr2->join();
 232
 233 If the program exits without all other threads having been either joined or
 234 detached, then a warning will be issued. (A program exits either because one
 235 of its threads explicitly calls L<exit()|perlfunc/"exit EXPR">, or in the case
 236 of the main thread, reaches the end of the main program file.)
 237
 238 Calling C<-E<gt>join()> or C<-E<gt>detach()> on an already joined thread will
 239 cause an error to be thrown.
 240
 241 =item $thr->detach()
 242
 243 Makes the thread unjoinable, and causes any eventual return value to be
 244 discarded.
 245
 246 Calling C<-E<gt>join()> or C<-E<gt>detach()> on an already detached thread
 247 will cause an error to be thrown.
 248
 249 =item threads->detach()
 250
 251 Class method that allows a thread to detach itself.
 252
 253 =item threads->self()
 254
 255 Class method that allows a thread to obtain its own I<threads> object.
 256
 257 =item $thr->tid()
 258
 259 Returns the ID of the thread.  Thread IDs are unique integers with the main
 260 thread in a program being 0, and incrementing by 1 for every thread created.
 261
 262 =item threads->tid()
 263
 264 Class method that allows a thread to obtain its own ID.
 265
 266 =item threads->object($tid)
 267
 268 This will return the I<threads> object for the I<active> thread associated
 269 with the specified thread ID.  Returns C<undef> if there is no thread
 270 associated with the TID, if the thread is joined or detached, if no TID is
 271 specified or if the specified TID is undef.
 272
 273 =item threads->yield()
 274
 275 This is a suggestion to the OS to let this thread yield CPU time to other
 276 threads.  What actually happens is highly dependent upon the underlying
 277 thread implementation.
 278
 279 You may do C<use threads qw(yield)>, and then just use C<yield()> in your
 280 code.
 281
 282 =item threads->list()
 283
 284 In a list context, returns a list of all non-joined, non-detached I<threads>
 285 objects.  In a scalar context, returns a count of the same.
 286
 287 =item $thr1->equal($thr2)
 288
 289 Tests if two threads objects are the same thread or not.  This is overloaded
 290 to the more natural forms:
 291
 292     if ($thr1 == $thr2) {
 293         print("Threads are the same\n");
 294     }
 295     # or
 296     if ($thr1 != $thr2) {
 297         print("Threads differ\n");
 298     }
 299
 300 (Thread comparison is based on thread IDs.)
 301
 302 =item async BLOCK;
 303
 304 C<async> creates a thread to execute the block immediately following
 305 it.  This block is treated as an anonymous subroutine, and so must have a
 306 semi-colon after the closing brace.  Like C<threads->create()>, C<async>
 307 returns a I<threads> object.
 308
 309 =item $thr->_handle()
 310
 311 This I<private> method returns the memory location of the internal thread
 312 structure associated with a threads object.  For Win32, this is a pointer to
 313 the C<HANDLE> value returned by C<CreateThread> (i.e., C<HANDLE *>); for other
 314 platforms, it is a pointer to the C<pthread_t> structure used in the
 315 C<pthread_create> call (i.e., C<pthread_t *>.
 316
 317 This method is of no use for general Perl threads programming.  Its intent is
 318 to provide other (XS-based) thread modules with the capability to access, and
 319 possibly manipulate, the underlying thread structure associated with a Perl
 320 thread.
 321
 322 =item threads->_handle()
 323
 324 Class method that allows a thread to obtain its own I<handle>.
 325
 326 =back
 327
 328 =head1 THREAD STACK SIZE
 329
 330 The default per-thread stack size for different platforms varies
 331 significantly, and is almost always far more than is needed for most
 332 applications.  On Win32, Perl's makefile explicitly sets the default stack to
 333 16 MB; on most other platforms, the system default is used, which again may be
 334 much larger than is needed.
 335
 336 By tuning the stack size to more accurately reflect your application's needs,
 337 you may significantly reduce your application's memory usage, and increase the
 338 number of simultaneously running threads.
 339
 340 N.B., on Windows, Address space allocation granularity is 64 KB, therefore,
 341 setting the stack smaller than that on Win32 Perl will not save any more
 342 memory.
 343
 344 =over
 345
 346 =item threads->get_stack_size();
 347
 348 Returns the current default per-thread stack size.  The default is zero, which
 349 means the system default stack size is currently in use.
 350
 351 =item $size = $thr->get_stack_size();
 352
 353 Returns the stack size for a particular thread.  A return value of zero
 354 indicates the system default stack size was used for the thread.
 355
 356 =item $old_size = threads->set_stack_size($new_size);
 357
 358 Sets a new default per-thread stack size, and returns the previous setting.
 359
 360 Some platforms have a minimum thread stack size.  Trying to set the stack size
 361 below this value will result in a warning, and the minimum stack size will be
 362 used.
 363
 364 Some Linux platforms have a maximum stack size.  Setting too large of a stack
 365 size will cause thread creation to fail.
 366
 367 If needed, C<$new_size> will be rounded up to the next multiple of the memory
 368 page size (usually 4096 or 8192).
 369
 370 Threads created after the stack size is set will then either call
 371 C<pthread_attr_setstacksize()> I<(for pthreads platforms)>, or supply the
 372 stack size to C<CreateThread()> I<(for Win32 Perl)>.
 373
 374 (Obviously, this call does not affect any currently extant threads.)
 375
 376 =item use threads ('stack_size' => VALUE);
 377
 378 This sets the default per-thread stack size at the start of the application.
 379
 380 =item $ENV{'PERL5_ITHREADS_STACK_SIZE'}
 381
 382 The default per-thread stack size may be set at the start of the application
 383 through the use of the environment variable C<PERL5_ITHREADS_STACK_SIZE>:
 384
 385     PERL5_ITHREADS_STACK_SIZE=1048576
 386     export PERL5_ITHREADS_STACK_SIZE
 387     perl -e'use threads; print(threads->get_stack_size(), "\n")'
 388
 389 This value overrides any C<stack_size> parameter given to C<use threads>.  Its
 390 primary purpose is to permit setting the per-thread stack size for legacy
 391 threaded applications.
 392
 393 =item threads->create({'stack_size' => VALUE}, FUNCTION, ARGS)
 394
 395 This change to the thread creation method permits specifying the stack size
 396 for an individual thread.
 397
 398 =item $thr2 = $thr1->create(FUNCTION, ARGS)
 399
 400 This creates a new thread (C<$thr2>) that inherits the stack size from an
 401 existing thread (C<$thr1>).  This is shorthand for the following:
 402
 403     my $stack_size = $thr1->get_stack_size();
 404     my $thr2 = threads->create({'stack_size' => $stack_size}, FUNCTION, ARGS);
 405
 406 =back
 407
 408 =head1 WARNINGS
 409
 410 =over 4
 411
 412 =item A thread exited while # other threads were still running
 413
 414 A thread (not necessarily the main thread) exited while there were still other
 415 threads running.  Usually, it's a good idea to first collect the return values
 416 of the created threads by joining them, and only then exit from the main
 417 thread.
 418
 419 =item Using minimum thread stack size of #
 420
 421 Some platforms have a minimum thread stack size.  Trying to set the stack size
 422 below this value will result in the above warning, and the stack size will be
 423 set to the minimum.
 424
 425 =back
 426
 427 =head1 ERRORS
 428
 429 =over 4
 430
 431 =item This Perl not built to support threads
 432
 433 The particular copy of Perl that you're trying to use was not built using the
 434 C<useithreads> configuration option.
 435
 436 Having threads support requires all of Perl and all of the XS modules in the
 437 Perl installation to be rebuilt; it is not just a question of adding the
 438 L<threads> module (i.e., threaded and non-threaded Perls are binary
 439 incompatible.)
 440
 441 =item Cannot change stack size of an existing thread
 442
 443 The stack size of currently extant threads cannot be changed, therefore, the
 444 following results in the above error:
 445
 446     $thr->set_stack_size($size);
 447
 448 =item Thread creation failed: pthread_attr_setstacksize(I<SIZE>) returned 22
 449
 450 The specified I<SIZE> exceeds the system's maximum stack size.  Use a smaller
 451 value for the stack size.
 452
 453 =back
 454
 455 =head1 BUGS
 456
 457 =over
 458
 459 =item Parent-child threads
 460
 461 On some platforms, it might not be possible to destroy I<parent> threads while
 462 there are still existing I<child> threads.
 463
 464 =item Creating threads inside BEGIN blocks
 465
 466 Creating threads inside BEGIN blocks (or during the compilation phase in
 467 general) does not work.  (In Windows, trying to use fork() inside BEGIN blocks
 468 is an equally losing proposition, since it has been implemented in very much
 469 the same way as threads.)
 470
 471 =item PERL_OLD_SIGNALS are not threadsafe, will not be.
 472
 473 If your Perl has been built with PERL_OLD_SIGNALS (one has to explicitly add
 474 that symbol to I<ccflags>, see C<perl -V>), signal handling is not threadsafe.
 475
 476 =item Returning closures from threads
 477
 478 Returning a closure from a thread does not work, usually crashing Perl in the
 479 process.
 480
 481 =item Perl Bugs and the CPAN Version of L<threads>
 482
 483 Support for threads extents beyond the code in this module (i.e.,
 484 F<threads.pm> and F<threads.xs>), and into the Perl iterpreter itself.  Older
 485 versions of Perl contain bugs that may manifest themselves despite using the
 486 latest version of L<threads> from CPAN.  There is no workaround for this other
 487 than upgrading to the lastest version of Perl.
 488
 489 (Before you consider posting a bug report, please consult, and possibly post a
 490 message to the discussion forum to see if what you've encountered is a known
 491 problem.)
 492
 493 =back
 494
 495 =head1 REQUIREMENTS
 496
 497 Perl 5.8.0 or later
 498
 499 =head1 SEE ALSO
 500
 501 L<threads> Discussion Forum on CPAN:
 502 L<http://www.cpanforum.com/dist/threads>
 503
 504 Annotated POD for L<threads>:
 505 L<http://annocpan.org/~JDHEDDEN/threads-1.25/shared.pm>
 506
 507 L<threads::shared>, L<perlthrtut>
 508
 509 L<http://www.perl.com/pub/a/2002/06/11/threads.html> and
 510 L<http://www.perl.com/pub/a/2002/09/04/threads.html>
 511
 512 Perl threads mailing list:
 513 L<http://lists.cpan.org/showlist.cgi?name=iThreads>
 514
 515 Stack size discussion:
 516 L<http://www.perlmonks.org/?node_id=532956>
 517
 518 =head1 AUTHOR
 519
 520 Artur Bergman E<lt>sky AT crucially DOT netE<gt>
 521
 522 threads is released under the same license as Perl.
 523
 524 CPAN version produced by Jerry D. Hedden <jdhedden AT cpan DOT org>
 525
 526 =head1 ACKNOWLEDGEMENTS
 527
 528 Richard Soderberg E<lt>perl AT crystalflame DOT netE<gt> -
 529 Helping me out tons, trying to find reasons for races and other weird bugs!
 530
 531 Simon Cozens E<lt>simon AT brecon DOT co DOT ukE<gt> -
 532 Being there to answer zillions of annoying questions
 533
 534 Rocco Caputo E<lt>troc AT netrus DOT netE<gt>
 535
 536 Vipul Ved Prakash E<lt>mail AT vipul DOT netE<gt> -
 537 Helping with debugging
 538
 539 Dean Arnold E<lt>darnold AT presicient DOT comE<gt> -
 540 Stack size API
 541
 542 =cut