contrib/perl5/ext/Thread/Thread.pm

   1 package Thread;
   2 require Exporter;
   3 require DynaLoader;
   4 use vars qw($VERSION @ISA @EXPORT);
   5
   6 $VERSION = "1.0";
   7
   8 @ISA = qw(Exporter DynaLoader);
   9 @EXPORT_OK = qw(yield cond_signal cond_broadcast cond_wait async);
  10
  11 =head1 NAME
  12
  13 Thread - multithreading
  14
  15 =head1 SYNOPSIS
  16
  17     use Thread;
  18
  19     my $t = new Thread \&start_sub, @start_args;
  20
  21     $t->join;
  22
  23     my $tid = Thread->self->tid;
  24
  25     my $tlist = Thread->list;
  26
  27     lock($scalar);
  28
  29     use Thread 'async';
  30
  31     use Thread 'eval';
  32
  33 =head1 DESCRIPTION
  34
  35 The C<Thread> module provides multithreading support for perl.
  36
  37 =head1 FUNCTIONS
  38
  39 =over 8
  40
  41 =item new \&start_sub
  42
  43 =item new \&start_sub, LIST
  44
  45 C<new> starts a new thread of execution in the referenced subroutine. The
  46 optional list is passed as parameters to the subroutine. Execution
  47 continues in both the subroutine and the code after the C<new> call.
  48
  49 C<new Thread> returns a thread object representing the newly created
  50 thread.
  51
  52 =item lock VARIABLE
  53
  54 C<lock> places a lock on a variable until the lock goes out of scope.  If
  55 the variable is locked by another thread, the C<lock> call will block until
  56 it's available. C<lock> is recursive, so multiple calls to C<lock> are
  57 safe--the variable will remain locked until the outermost lock on the
  58 variable goes out of scope.
  59
  60 Locks on variables only affect C<lock> calls--they do I<not> affect normal
  61 access to a variable. (Locks on subs are different, and covered in a bit)
  62 If you really, I<really> want locks to block access, then go ahead and tie
  63 them to something and manage this yourself. This is done on purpose. While
  64 managing access to variables is a good thing, perl doesn't force you out of
  65 its living room...
  66
  67 If a container object, such as a hash or array, is locked, all the elements
  68 of that container are not locked. For example, if a thread does a C<lock
  69 @a>, any other thread doing a C<lock($a[12])> won't block.
  70
  71 You may also C<lock> a sub, using C<lock &sub>. Any calls to that sub from
  72 another thread will block until the lock is released. This behaviour is not
  73 equvalent to C<use attrs qw(locked)> in the sub. C<use attrs qw(locked)>
  74 serializes access to a subroutine, but allows different threads
  75 non-simultaneous access. C<lock &sub>, on the other hand, will not allow
  76 I<any> other thread access for the duration of the lock.
  77
  78 Finally, C<lock> will traverse up references exactly I<one> level.
  79 C<lock(\$a)> is equivalent to C<lock($a)>, while C<lock(\\$a)> is not.
  80
  81 =item async BLOCK;
  82
  83 C<async> creates a thread to execute the block immediately following
  84 it. This block is treated as an anonymous sub, and so must have a
  85 semi-colon after the closing brace. Like C<new Thread>, C<async> returns a
  86 thread object.
  87
  88 =item Thread->self
  89
  90 The C<Thread-E<gt>self> function returns a thread object that represents
  91 the thread making the C<Thread-E<gt>self> call.
  92
  93 =item Thread->list
  94
  95 C<Thread-E<gt>list> returns a list of thread objects for all running and
  96 finished but un-C<join>ed threads.
  97
  98 =item cond_wait VARIABLE
  99
 100 The C<cond_wait> function takes a B<locked> variable as a parameter,
 101 unlocks the variable, and blocks until another thread does a C<cond_signal>
 102 or C<cond_broadcast> for that same locked variable. The variable that
 103 C<cond_wait> blocked on is relocked after the C<cond_wait> is satisfied.
 104 If there are multiple threads C<cond_wait>ing on the same variable, all but
 105 one will reblock waiting to reaquire the lock on the variable. (So if
 106 you're only using C<cond_wait> for synchronization, give up the lock as
 107 soon as possible)
 108
 109 =item cond_signal VARIABLE
 110
 111 The C<cond_signal> function takes a locked variable as a parameter and
 112 unblocks one thread that's C<cond_wait>ing on that variable. If more than
 113 one thread is blocked in a C<cond_wait> on that variable, only one (and
 114 which one is indeterminate) will be unblocked.
 115
 116 If there are no threads blocked in a C<cond_wait> on the variable, the
 117 signal is discarded.
 118
 119 =item cond_broadcast VARIABLE
 120
 121 The C<cond_broadcast> function works similarly to C<cond_wait>.
 122 C<cond_broadcast>, though, will unblock B<all> the threads that are blocked
 123 in a C<cond_wait> on the locked variable, rather than only one.
 124
 125 =back
 126
 127 =head1 METHODS
 128
 129 =over 8
 130
 131 =item join
 132
 133 C<join> waits for a thread to end and returns any values the thread exited
 134 with. C<join> will block until the thread has ended, though it won't block
 135 if the thread has already terminated.
 136
 137 If the thread being C<join>ed C<die>d, the error it died with will be
 138 returned at this time. If you don't want the thread performing the C<join>
 139 to die as well, you should either wrap the C<join> in an C<eval> or use the
 140 C<eval> thread method instead of C<join>.
 141
 142 =item eval
 143
 144 The C<eval> method wraps an C<eval> around a C<join>, and so waits for a
 145 thread to exit, passing along any values the thread might have returned.
 146 Errors, of course, get placed into C<$@>.
 147
 148 =item tid
 149
 150 The C<tid> method returns the tid of a thread. The tid is a monotonically
 151 increasing integer assigned when a thread is created. The main thread of a
 152 program will have a tid of zero, while subsequent threads will have tids
 153 assigned starting with one.
 154
 155 =head1 LIMITATIONS
 156
 157 The sequence number used to assign tids is a simple integer, and no
 158 checking is done to make sure the tid isn't currently in use. If a program
 159 creates more than 2^32 - 1 threads in a single run, threads may be assigned
 160 duplicate tids. This limitation may be lifted in a future version of Perl.
 161
 162 =head1 SEE ALSO
 163
 164 L<attrs>, L<Thread::Queue>, L<Thread::Semaphore>, L<Thread::Specific>.
 165
 166 =cut
 167
 168 #
 169 # Methods
 170 #
 171
 172 #
 173 # Exported functions
 174 #
 175 sub async (&) {
 176     return new Thread $_[0];
 177 }
 178
 179 sub eval {
 180     return eval { shift->join; };
 181 }
 182
 183 bootstrap Thread;
 184
 185 1;