From: Dan Sugalski Date: Wed, 8 Apr 1998 17:08:48 +0000 (-0700) Subject: [PATCH 5.004_64] Final (I hope) doc patch for Thread.pm X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=589fe9d5e99683526640f3a7119bb0059e22bc5f;p=p5sagit%2Fp5-mst-13.2.git [PATCH 5.004_64] Final (I hope) doc patch for Thread.pm Date: Wed, 08 Apr 1998 17:08:48 -0700 Subject: [PATCH 5.004_64] Revised second Thread.PM doc patch Date: Fri, 08 May 1998 10:49:16 -0700 p4raw-id: //depot/perl@962 --- diff --git a/ext/Thread/Thread.pm b/ext/Thread/Thread.pm index cf7069c..c8bca0d 100644 --- a/ext/Thread/Thread.pm +++ b/ext/Thread/Thread.pm @@ -32,7 +32,132 @@ Thread - multithreading =head1 DESCRIPTION -The C module provides multithreading. +The C module provides multithreading support for perl. + +=head1 FUNCTIONS + +=over 8 + +=item new \&start_sub + +=item new \&start_sub, LIST + +C starts a new thread of execution in the referenced subroutine. The +optional list is passed as parameters to the subroutine. Execution +continues in both the subroutine and the code after the C call. + +C returns a thread object representing the newly created +thread. + +=item lock VARIABLE + +C places a lock on a variable until the lock goes out of scope. If +the variable is locked by another thread, the C call will block until +it's available. C is recursive, so multiple calls to C are +safe--the variable will remain locked until the outermost lock on the +variable goes out of scope. + +Locks on variables only affect C calls--they do I affect normal +access to a variable. (Locks on subs are different, and covered in a bit) +If you really, I want locks to block access, then go ahead and tie +them to something and manage this yourself. This is done on purpose. While +managing access to variables is a good thing, perl doesn't force you out of +its living room... + +If a container object, such as a hash or array, is locked, all the elements +of that container are not locked. For example, if a thread does a C, any other thread doing a C won't block. + +You may also C a sub, using C. Any calls to that sub from +another thread will block until the lock is released. This behaviour is not +equvalent to C in the sub. C +serializes access to a subroutine, but allows different threads +non-simultaneous access. C, on the other hand, will not allow +I other thread access for the duration of the lock. + +Finally, C will traverse up references exactly I level. +C is equivalent to C, while C is not. + +=item async BLOCK; + +C creates a thread to execute the block immediately following +it. This block is treated as an anonymous sub, and so must have a +semi-colon after the closing brace. Like C, C returns a +thread object. + +=item Thread->self + +The Cself> function returns a thread object that represents +the thread making the Cself> call. + +=item Thread->list + +Clist> returns a list of thread objects for all running and +finished but un-Ced threads. + +=item cond_wait VARIABLE + +The C function takes a B variable as a parameter, +unlocks the variable, and blocks until another thread does a C +or C for that same locked variable. The variable that +C blocked on is relocked after the C is satisfied. +If there are multiple threads Cing on the same variable, all but +one will reblock waiting to reaquire the lock on the variable. (So if +you're only using C for synchronization, give up the lock as +soon as possible) + +=item cond_signal VARIABLE + +The C function takes a locked variable as a parameter and +unblocks one thread that's Cing on that variable. If more than +one thread is blocked in a C on that variable, only one (and +which one is indeterminate) will be unblocked. + +If there are no threads blocked in a C on the variable, the +signal is discarded. + +=item cond_broadcast VARIABLE + +The C function works similarly to C. +C, though, will unblock B the threads that are blocked +in a C on the locked variable, rather than only one. + +=back + +=head1 METHODS + +=over 8 + +=item join + +C waits for a thread to end and returns any values the thread exited +with. C will block until the thread has ended, though it won't block +if the thread has already terminated. + +If the thread being Ced Cd, the error it died with will be +returned at this time. If you don't want the thread performing the C +to die as well, you should either wrap the C in an C or use the +C thread method instead of C. + +=item eval + +The C method wraps an C around a C, and so waits for a +thread to exit, passing along any values the thread might have returned. +Errors, of course, get placed into C<$@>. + +=item tid + +The C method returns the tid of a thread. The tid is a monotonically +increasing integer assigned when a thread is created. The main thread of a +program will have a tid of zero, while subsequent threads will have tids +assigned starting with one. + +=head1 LIMITATIONS + +The sequence number used to assign tids is a simple integer, and no +checking is done to make sure the tid isn't currently in use. If a program +creates more than 2^32 - 1 threads in a single run, threads may be assigned +duplicate tids. This limitation may be lifted in a future version of Perl. =head1 SEE ALSO