ext/Thread/Thread.pm

   1 package Thread;
   2 require Exporter;
   3 use XSLoader ();
   4 our($VERSION, @ISA, @EXPORT);
   5
   6 $VERSION = "1.0";
   7
   8 @ISA = qw(Exporter);
   9 @EXPORT_OK = qw(yield cond_signal cond_broadcast cond_wait async);
  10
  11 =head1 NAME
  12
  13 Thread - manipulate threads in Perl (EXPERIMENTAL, subject to change)
  14
  15 =head1 SYNOPSIS
  16
  17     use Thread;
  18
  19     my $t = new Thread \&start_sub, @start_args;
  20
  21     $result = $t->join;
  22     $result = $t->eval;
  23     $t->detach;
  24     $flags = $t->flags;
  25
  26     if ($t->done) {
  27         $t->join;
  28     }
  29
  30     if($t->equal($another_thread)) {
  31         # ...
  32     }
  33
  34     my $tid = Thread->self->tid;
  35     my $tlist = Thread->list;
  36
  37
  38     lock($scalar);
  39     yield();
  40
  41     use Thread 'async';
  42
  43 =head1 DESCRIPTION
  44
  45     WARNING: Threading is an experimental feature.  Both the interface
  46     and implementation are subject to change drastically.  In fact, this
  47     documentation describes the flavor of threads that was in version
  48     5.005.  Perl 5.6.0 and later have the beginnings of support for
  49     interpreter threads, which (when finished) is expected to be
  50     significantly different from what is described here.  The information
  51     contained here may therefore soon be obsolete.  Use at your own risk!
  52
  53 The C<Thread> module provides multithreading support for perl.
  54
  55 =head1 FUNCTIONS
  56
  57 =over 8
  58
  59 =item new \&start_sub
  60
  61 =item new \&start_sub, LIST
  62
  63 C<new> starts a new thread of execution in the referenced subroutine. The
  64 optional list is passed as parameters to the subroutine. Execution
  65 continues in both the subroutine and the code after the C<new> call.
  66
  67 C<new Thread> returns a thread object representing the newly created
  68 thread.
  69
  70 =item lock VARIABLE
  71
  72 C<lock> places a lock on a variable until the lock goes out of scope.  If
  73 the variable is locked by another thread, the C<lock> call will block until
  74 it's available. C<lock> is recursive, so multiple calls to C<lock> are
  75 safe--the variable will remain locked until the outermost lock on the
  76 variable goes out of scope.
  77
  78 Locks on variables only affect C<lock> calls--they do I<not> affect normal
  79 access to a variable. (Locks on subs are different, and covered in a bit)
  80 If you really, I<really> want locks to block access, then go ahead and tie
  81 them to something and manage this yourself. This is done on purpose. While
  82 managing access to variables is a good thing, perl doesn't force you out of
  83 its living room...
  84
  85 If a container object, such as a hash or array, is locked, all the elements
  86 of that container are not locked. For example, if a thread does a C<lock
  87 @a>, any other thread doing a C<lock($a[12])> won't block.
  88
  89 You may also C<lock> a sub, using C<lock &sub>. Any calls to that sub from
  90 another thread will block until the lock is released. This behaviour is not
  91 equivalent to declaring the sub with the C<locked> attribute.  The C<locked>
  92 attribute serializes access to a subroutine, but allows different threads
  93 non-simultaneous access. C<lock &sub>, on the other hand, will not allow
  94 I<any> other thread access for the duration of the lock.
  95
  96 Finally, C<lock> will traverse up references exactly I<one> level.
  97 C<lock(\$a)> is equivalent to C<lock($a)>, while C<lock(\\$a)> is not.
  98
  99 =item async BLOCK;
 100
 101 C<async> creates a thread to execute the block immediately following
 102 it. This block is treated as an anonymous sub, and so must have a
 103 semi-colon after the closing brace. Like C<new Thread>, C<async> returns a
 104 thread object.
 105
 106 =item Thread->self
 107
 108 The C<Thread-E<gt>self> function returns a thread object that represents
 109 the thread making the C<Thread-E<gt>self> call.
 110
 111 =item Thread->list
 112
 113 C<Thread-E<gt>list> returns a list of thread objects for all running and
 114 finished but un-C<join>ed threads.
 115
 116 =item cond_wait VARIABLE
 117
 118 The C<cond_wait> function takes a B<locked> variable as a parameter,
 119 unlocks the variable, and blocks until another thread does a C<cond_signal>
 120 or C<cond_broadcast> for that same locked variable. The variable that
 121 C<cond_wait> blocked on is relocked after the C<cond_wait> is satisfied.
 122 If there are multiple threads C<cond_wait>ing on the same variable, all but
 123 one will reblock waiting to reaquire the lock on the variable. (So if
 124 you're only using C<cond_wait> for synchronization, give up the lock as
 125 soon as possible)
 126
 127 =item cond_signal VARIABLE
 128
 129 The C<cond_signal> function takes a locked variable as a parameter and
 130 unblocks one thread that's C<cond_wait>ing on that variable. If more than
 131 one thread is blocked in a C<cond_wait> on that variable, only one (and
 132 which one is indeterminate) will be unblocked.
 133
 134 If there are no threads blocked in a C<cond_wait> on the variable, the
 135 signal is discarded.
 136
 137 =item cond_broadcast VARIABLE
 138
 139 The C<cond_broadcast> function works similarly to C<cond_signal>.
 140 C<cond_broadcast>, though, will unblock B<all> the threads that are blocked
 141 in a C<cond_wait> on the locked variable, rather than only one.
 142
 143 =item yield
 144
 145 The C<yield> function allows another thread to take control of the
 146 CPU. The exact results are implementation-dependent.
 147
 148 =back
 149
 150 =head1 METHODS
 151
 152 =over 8
 153
 154 =item join
 155
 156 C<join> waits for a thread to end and returns any values the thread exited
 157 with. C<join> will block until the thread has ended, though it won't block
 158 if the thread has already terminated.
 159
 160 If the thread being C<join>ed C<die>d, the error it died with will be
 161 returned at this time. If you don't want the thread performing the C<join>
 162 to die as well, you should either wrap the C<join> in an C<eval> or use the
 163 C<eval> thread method instead of C<join>.
 164
 165 =item eval
 166
 167 The C<eval> method wraps an C<eval> around a C<join>, and so waits for a
 168 thread to exit, passing along any values the thread might have returned.
 169 Errors, of course, get placed into C<$@>.
 170
 171 =item detach
 172
 173 C<detach> tells a thread that it is never going to be joined i.e.
 174 that all traces of its existence can be removed once it stops running.
 175 Errors in detached threads will not be visible anywhere - if you want
 176 to catch them, you should use $SIG{__DIE__} or something like that.
 177
 178 =item equal
 179
 180 C<equal> tests whether two thread objects represent the same thread and
 181 returns true if they do.
 182
 183 =item tid
 184
 185 The C<tid> method returns the tid of a thread. The tid is a monotonically
 186 increasing integer assigned when a thread is created. The main thread of a
 187 program will have a tid of zero, while subsequent threads will have tids
 188 assigned starting with one.
 189
 190 =item flags
 191
 192 The C<flags> method returns the flags for the thread. This is the
 193 integer value corresponding to the internal flags for the thread, and
 194 the value man not be all that meaningful to you.
 195
 196 =item done
 197
 198 The C<done> method returns true if the thread you're checking has
 199 finished, and false otherwise.
 200
 201 =back
 202
 203 =head1 LIMITATIONS
 204
 205 The sequence number used to assign tids is a simple integer, and no
 206 checking is done to make sure the tid isn't currently in use. If a program
 207 creates more than 2^32 - 1 threads in a single run, threads may be assigned
 208 duplicate tids. This limitation may be lifted in a future version of Perl.
 209
 210 =head1 SEE ALSO
 211
 212 L<attributes>, L<Thread::Queue>, L<Thread::Semaphore>, L<Thread::Specific>.
 213
 214 =cut
 215
 216 #
 217 # Methods
 218 #
 219
 220 #
 221 # Exported functions
 222 #
 223 sub async (&) {
 224     return new Thread $_[0];
 225 }
 226
 227 sub eval {
 228     return eval { shift->join; };
 229 }
 230
 231 XSLoader::load 'Thread';
 232
 233 1;