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 require Exporter;
  42 require DynaLoader;
  43
  44 our @ISA = qw(Exporter DynaLoader);
  45
  46 our %EXPORT_TAGS = ( all => [qw(yield)]);
  47
  48 our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
  49
  50 our @EXPORT = qw(
  51 async
  52 );
  53 our $VERSION = '1.03';
  54
  55
  56 # || 0 to ensure compatibility with previous versions
  57 sub equal { ($_[0]->tid == $_[1]->tid) || 0 }
  58
  59 # use "goto" trick to avoid pad problems from 5.8.1, should also be faster
  60 sub async (&;@) { unshift @_,'threads'; goto &new }
  61
  62 sub object {
  63     return undef unless @_ > 1;
  64     foreach (threads->list) {
  65         return $_ if $_->tid == $_[1];
  66     }
  67     return undef;
  68 }
  69
  70 $threads::threads = 1;
  71
  72 bootstrap threads $VERSION;
  73
  74 # why document 'new' then use 'create' in the tests!
  75 *create = \&new;
  76
  77 # Preloaded methods go here.
  78
  79 1;
  80 __END__
  81
  82 =head1 NAME
  83
  84 threads - Perl extension allowing use of interpreter based threads from perl
  85
  86 =head1 SYNOPSIS
  87
  88     use threads;
  89
  90     sub start_thread {
  91         print "Thread started\n";
  92     }
  93
  94     my $thread  = threads->create("start_thread","argument");
  95     my $thread2 = $thread->create(sub { print "I am a thread"},"argument");
  96     my $thread3 = async { foreach (@files) { ... } };
  97
  98     $thread->join();
  99     $thread->detach();
 100
 101     $thread = threads->self();
 102     $thread = threads->object( $tid );
 103
 104     $thread->tid();
 105     threads->tid();
 106     threads->self->tid();
 107
 108     threads->yield();
 109
 110     threads->list();
 111
 112 =head1 DESCRIPTION
 113
 114 Perl 5.6 introduced something called interpreter threads.  Interpreter
 115 threads are different from "5005threads" (the thread model of Perl
 116 5.005) by creating a new perl interpreter per thread and not sharing
 117 any data or state between threads by default.
 118
 119 Prior to perl 5.8 this has only been available to people embedding
 120 perl and for emulating fork() on windows.
 121
 122 The threads API is loosely based on the old Thread.pm API. It is very
 123 important to note that variables are not shared between threads, all
 124 variables are per default thread local.  To use shared variables one
 125 must use threads::shared.
 126
 127 It is also important to note that you must enable threads by doing
 128 C<use threads> as early as possible in the script itself and that it
 129 is not possible to enable threading inside an C<eval "">, C<do>,
 130 C<require>, or C<use>.  In particular, if you are intending to share
 131 variables with threads::shared, you must C<use threads> before you
 132 C<use threads::shared> and C<threads> will emit a warning if you do
 133 it the other way around.
 134
 135 =over
 136
 137 =item $thread = threads->create(function, LIST)
 138
 139 This will create a new thread with the entry point function and give
 140 it LIST as parameters.  It will return the corresponding threads
 141 object. The new() method is an alias for create().
 142
 143 =item $thread->join
 144
 145 This will wait for the corresponding thread to join. When the thread
 146 finishes, join() will return the return values of the entry point
 147 function. If the thread has been detached, an error will be thrown.
 148
 149 The context (scalar or list) of the thread creation is also the
 150 context for join().  This means that if you intend to return an array
 151 from a thread, you must use C<my ($thread) = threads->new(...)>, and
 152 that if you intend to return a scalar, you must use C<my $thread = ...>.
 153
 154 If the program exits without all other threads having been either
 155 joined or detached, then a warning will be issued. (A program exits
 156 either because one of its threads explicitly calls exit(), or in the
 157 case of the main thread, reaches the end of the main program file.)
 158
 159
 160 =item $thread->detach
 161
 162 Will make the thread unjoinable, and cause any eventual return value
 163 to be discarded.
 164
 165 =item threads->self
 166
 167 This will return the thread object for the current thread.
 168
 169 =item $thread->tid
 170
 171 This will return the id of the thread.  Thread IDs are integers, with
 172 the main thread in a program being 0.  Currently Perl assigns a unique
 173 tid to every thread ever created in your program, assigning the first
 174 thread to be created a tid of 1, and increasing the tid by 1 for each
 175 new thread that's created.
 176
 177 NB the class method C<< threads->tid() >> is a quick way to get the
 178 current thread id if you don't have your thread object handy.
 179
 180 =item threads->object( tid )
 181
 182 This will return the thread object for the thread associated with the
 183 specified tid.  Returns undef if there is no thread associated with the tid
 184 or no tid is specified or the specified tid is undef.
 185
 186 =item threads->yield();
 187
 188 This is a suggestion to the OS to let this thread yield CPU time to other
 189 threads.  What actually happens is highly dependent upon the underlying
 190 thread implementation.
 191
 192 You may do C<use threads qw(yield)> then use just a bare C<yield> in your
 193 code.
 194
 195 =item threads->list();
 196
 197 This will return a list of all non joined, non detached threads.
 198
 199 =item async BLOCK;
 200
 201 C<async> creates a thread to execute the block immediately following
 202 it.  This block is treated as an anonymous sub, and so must have a
 203 semi-colon after the closing brace. Like C<< threads->new >>, C<async>
 204 returns a thread object.
 205
 206 =back
 207
 208 =head1 WARNINGS
 209
 210 =over 4
 211
 212 =item A thread exited while %d other threads were still running
 213
 214 A thread (not necessarily the main thread) exited while there were
 215 still other threads running.  Usually it's a good idea to first collect
 216 the return values of the created threads by joining them, and only then
 217 exit from the main thread.
 218
 219 =back
 220
 221 =head1 TODO
 222
 223 The current implementation of threads has been an attempt to get
 224 a correct threading system working that could be built on,
 225 and optimized, in newer versions of perl.
 226
 227 Currently the overhead of creating a thread is rather large,
 228 also the cost of returning values can be large. These are areas
 229 were there most likely will be work done to optimize what data
 230 that needs to be cloned.
 231
 232 =head1 BUGS
 233
 234 =over
 235
 236 =item Parent-Child threads.
 237
 238 On some platforms it might not be possible to destroy "parent"
 239 threads while there are still existing child "threads".
 240
 241 This will possibly be fixed in later versions of perl.
 242
 243 =item tid is I32
 244
 245 The thread id is a 32 bit integer, it can potentially overflow.
 246 This might be fixed in a later version of perl.
 247
 248 =item Returning objects
 249
 250 When you return an object the entire stash that the object is blessed
 251 as well.  This will lead to a large memory usage.  The ideal situation
 252 would be to detect the original stash if it existed.
 253
 254 =item Creating threads inside BEGIN blocks
 255
 256 Creating threads inside BEGIN blocks (or during the compilation phase
 257 in general) does not work.  (In Windows, trying to use fork() inside
 258 BEGIN blocks is an equally losing proposition, since it has been
 259 implemented in very much the same way as threads.)
 260
 261 =item PERL_OLD_SIGNALS are not threadsafe, will not be.
 262
 263 If your Perl has been built with PERL_OLD_SIGNALS (one has
 264 to explicitly add that symbol to ccflags, see C<perl -V>),
 265 signal handling is not threadsafe.
 266
 267 =back
 268
 269 =head1 AUTHOR and COPYRIGHT
 270
 271 Arthur Bergman E<lt>sky at nanisky.comE<gt>
 272
 273 threads is released under the same license as Perl.
 274
 275 Thanks to
 276
 277 Richard Soderberg E<lt>perl at crystalflame.netE<gt>
 278 Helping me out tons, trying to find reasons for races and other weird bugs!
 279
 280 Simon Cozens E<lt>simon at brecon.co.ukE<gt>
 281 Being there to answer zillions of annoying questions
 282
 283 Rocco Caputo E<lt>troc at netrus.netE<gt>
 284
 285 Vipul Ved Prakash E<lt>mail at vipul.netE<gt>
 286 Helping with debugging.
 287
 288 please join perl-ithreads@perl.org for more information
 289
 290 =head1 SEE ALSO
 291
 292 L<threads::shared>, L<perlthrtut>,
 293 L<http://www.perl.com/pub/a/2002/06/11/threads.html>,
 294 L<perlcall>, L<perlembed>, L<perlguts>
 295
 296 =cut