lib/Thread.pm

   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