[Summary view] [Print] [Text view]

   1  package Thread;
   2  
   3  use strict;
   4  use warnings;
   5  no warnings 'redefine';
   6  
   7  our $VERSION = '3.02';
   8  $VERSION = eval $VERSION;
   9  
  10  BEGIN {
  11      use Config;
  12      if (! $Config{useithreads}) {
  13          die("This Perl not built to support threads\n");
  14      }
  15  }
  16  
  17  use threads 'yield';
  18  use threads::shared;
  19  
  20  require Exporter;
  21  our @ISA = qw(Exporter threads);
  22  our @EXPORT = qw(cond_wait cond_broadcast cond_signal);
  23  our @EXPORT_OK = qw(async yield);
  24  
  25  sub async (&;@) { return Thread->new(shift); }
  26  
  27  sub done { return ! shift->is_running(); }
  28  
  29  sub eval  { die("'eval' not implemented with 'ithreads'\n"); };
  30  sub flags { die("'flags' not implemented with 'ithreads'\n"); };
  31  
  32  1;
  33  
  34  __END__
  35  
  36  =head1 NAME
  37  
  38  Thread - Manipulate threads in Perl (for old code only)
  39  
  40  =head1 DEPRECATED
  41  
  42  The C<Thread> module served as the frontend to the old-style thread model,
  43  called I<5005threads>, that was introduced in release 5.005.  That model was
  44  deprecated, and has been removed in version 5.10.
  45  
  46  For old code and interim backwards compatibility, the C<Thread> module has
  47  been reworked to function as a frontend for the new interpreter threads
  48  (I<ithreads>) model.  However, some previous functionality is not available.
  49  Further, the data sharing models between the two thread models are completely
  50  different, and anything to do with data sharing has to be thought differently.
  51  With I<ithreads>, you must explicitly C<share()> variables between the
  52  threads.
  53  
  54  You are strongly encouraged to migrate any existing threaded code to the new
  55  model (i.e., use the C<threads> and C<threads::shared> modules) as soon as
  56  possible.
  57  
  58  =head1 HISTORY
  59  
  60  In Perl 5.005, the thread model was that all data is implicitly shared, and
  61  shared access to data has to be explicitly synchronized.  This model is called
  62  I<5005threads>.
  63  
  64  In Perl 5.6, a new model was introduced in which all is was thread local and
  65  shared access to data has to be explicitly declared.  This model is called
  66  I<ithreads>, for "interpreter threads".
  67  
  68  In Perl 5.6, the I<ithreads> model was not available as a public API; only as
  69  an internal API that was available for extension writers, and to implement
  70  fork() emulation on Win32 platforms.
  71  
  72  In Perl 5.8, the I<ithreads> model became available through the C<threads>
  73  module, and the I<5005threads> model was deprecated.
  74  
  75  In Perl 5.10, the I<5005threads> model was removed from the Perl interpreter.
  76  
  77  =head1 SYNOPSIS
  78  
  79      use Thread qw(:DEFAULT async yield);
  80  
  81      my $t = Thread->new(\&start_sub, @start_args);
  82  
  83      $result = $t->join;
  84      $t->detach;
  85  
  86      if ($t->done) {
  87          $t->join;
  88      }
  89  
  90      if($t->equal($another_thread)) {
  91          # ...
  92      }
  93  
  94      yield();
  95  
  96      my $tid = Thread->self->tid;
  97  
  98      lock($scalar);
  99      lock(@array);
 100      lock(%hash);
 101  
 102      my @list = Thread->list;
 103  
 104  =head1 DESCRIPTION
 105  
 106  The C<Thread> module provides multithreading support for Perl.
 107  
 108  =head1 FUNCTIONS
 109  
 110  =over 8
 111  
 112  =item $thread = Thread->new(\&start_sub)
 113  
 114  =item $thread = Thread->new(\&start_sub, LIST)
 115  
 116  C<new> starts a new thread of execution in the referenced subroutine. The
 117  optional list is passed as parameters to the subroutine. Execution
 118  continues in both the subroutine and the code after the C<new> call.
 119  
 120  C<Thread-&gt;new> returns a thread object representing the newly created
 121  thread.
 122  
 123  =item lock VARIABLE
 124  
 125  C<lock> places a lock on a variable until the lock goes out of scope.
 126  
 127  If the variable is locked by another thread, the C<lock> call will
 128  block until it's available.  C<lock> is recursive, so multiple calls
 129  to C<lock> are safe--the variable will remain locked until the
 130  outermost lock on the variable goes out of scope.
 131  
 132  Locks on variables only affect C<lock> calls--they do I<not> affect normal
 133  access to a variable. (Locks on subs are different, and covered in a bit.)
 134  If you really, I<really> want locks to block access, then go ahead and tie
 135  them to something and manage this yourself.  This is done on purpose.
 136  While managing access to variables is a good thing, Perl doesn't force
 137  you out of its living room...
 138  
 139  If a container object, such as a hash or array, is locked, all the
 140  elements of that container are not locked. For example, if a thread
 141  does a C<lock @a>, any other thread doing a C<lock($a[12])> won't
 142  block.
 143  
 144  Finally, C<lock> will traverse up references exactly I<one> level.
 145  C<lock(\$a)> is equivalent to C<lock($a)>, while C<lock(\\$a)> is not.
 146  
 147  =item async BLOCK;
 148  
 149  C<async> creates a thread to execute the block immediately following
 150  it.  This block is treated as an anonymous sub, and so must have a
 151  semi-colon after the closing brace. Like C<Thread-&gt;new>, C<async>
 152  returns a thread object.
 153  
 154  =item Thread->self
 155  
 156  The C<Thread-E<gt>self> function returns a thread object that represents
 157  the thread making the C<Thread-E<gt>self> call.
 158  
 159  =item Thread->list
 160  
 161  Returns a list of all non-joined, non-detached Thread objects.
 162  
 163  =item cond_wait VARIABLE
 164  
 165  The C<cond_wait> function takes a B<locked> variable as
 166  a parameter, unlocks the variable, and blocks until another thread
 167  does a C<cond_signal> or C<cond_broadcast> for that same locked
 168  variable. The variable that C<cond_wait> blocked on is relocked
 169  after the C<cond_wait> is satisfied.  If there are multiple threads
 170  C<cond_wait>ing on the same variable, all but one will reblock waiting
 171  to reaquire the lock on the variable.  (So if you're only using
 172  C<cond_wait> for synchronization, give up the lock as soon as
 173  possible.)
 174  
 175  =item cond_signal VARIABLE
 176  
 177  The C<cond_signal> function takes a locked variable as a parameter and
 178  unblocks one thread that's C<cond_wait>ing on that variable. If more than
 179  one thread is blocked in a C<cond_wait> on that variable, only one (and
 180  which one is indeterminate) will be unblocked.
 181  
 182  If there are no threads blocked in a C<cond_wait> on the variable,
 183  the signal is discarded.
 184  
 185  =item cond_broadcast VARIABLE
 186  
 187  The C<cond_broadcast> function works similarly to C<cond_signal>.
 188  C<cond_broadcast>, though, will unblock B<all> the threads that are
 189  blocked in a C<cond_wait> on the locked variable, rather than only
 190  one.
 191  
 192  =item yield
 193  
 194  The C<yield> function allows another thread to take control of the
 195  CPU. The exact results are implementation-dependent.
 196  
 197  =back
 198  
 199  =head1 METHODS
 200  
 201  =over 8
 202  
 203  =item join
 204  
 205  C<join> waits for a thread to end and returns any values the thread
 206  exited with.  C<join> will block until the thread has ended, though
 207  it won't block if the thread has already terminated.
 208  
 209  If the thread being C<join>ed C<die>d, the error it died with will
 210  be returned at this time. If you don't want the thread performing
 211  the C<join> to die as well, you should either wrap the C<join> in
 212  an C<eval> or use the C<eval> thread method instead of C<join>.
 213  
 214  =item detach
 215  
 216  C<detach> tells a thread that it is never going to be joined i.e.
 217  that all traces of its existence can be removed once it stops running.
 218  Errors in detached threads will not be visible anywhere - if you want
 219  to catch them, you should use $SIG{__DIE__} or something like that.
 220  
 221  =item equal
 222  
 223  C<equal> tests whether two thread objects represent the same thread and
 224  returns true if they do.
 225  
 226  =item tid
 227  
 228  The C<tid> method returns the tid of a thread. The tid is
 229  a monotonically increasing integer assigned when a thread is
 230  created. The main thread of a program will have a tid of zero,
 231  while subsequent threads will have tids assigned starting with one.
 232  
 233  =item done
 234  
 235  The C<done> method returns true if the thread you're checking has
 236  finished, and false otherwise.
 237  
 238  =back
 239  
 240  =head1 DEFUNCT
 241  
 242  The following were implemented with I<5005threads>, but are no longer
 243  available with I<ithreads>.
 244  
 245  =over 8
 246  
 247  =item lock(\&sub)
 248  
 249  With 5005threads, you could also C<lock> a sub such that any calls to that sub
 250  from another thread would block until the lock was released.
 251  
 252  Also, subroutines could be declared with the C<:locked> attribute which would
 253  serialize access to the subroutine, but allowed different threads
 254  non-simultaneous access.
 255  
 256  =item eval
 257  
 258  The C<eval> method wrapped an C<eval> around a C<join>, and so waited for a
 259  thread to exit, passing along any values the thread might have returned and
 260  placing any errors into C<$@>.
 261  
 262  =item flags
 263  
 264  The C<flags> method returned the flags for the thread - an integer value
 265  corresponding to the internal flags for the thread.
 266  
 267  =back
 268  
 269  =head1 SEE ALSO
 270  
 271  L<threads>, L<threads::shared>, L<Thread::Queue>, L<Thread::Semaphore>
 272  
 273  =cut