Update README.threads

p4raw-id: //depot/perl@58

1 files changed, 71 insertions, 66 deletions

diff --git a/README.threads b/README.threads
index a60a897500..9e7b4d439b 100644
--- a/README.threads
+++ b/README.threads
@@ -1,62 +1,3 @@
-Background
-
-Some old globals (e.g. stack_sp, op) and some old per-interpreter
-variables (e.g. tmps_stack, cxstack) move into struct thread.
-All fields of struct thread (apart from a few only applicable to
-FAKE_THREADS) are of the form Tfoo. For example, stack_sp becomes
-the field Tstack_sp of struct thread. For those fields which moved
-from original perl, thread.h does
-    #define foo (thr->Tfoo)
-This means that all functions in perl which need to use one of these
-fields need an (automatic) variable thr which points at the current
-thread's struct thread. For pp_foo functions, it is passed around as
-an argument, for other functions they do
-    dTHR;
-which declares and initialises thr from thread-specific data
-via pthread_getspecific. If a function fails to compile with an
-error about "no such variable thr", it probably just needs a dTHR
-at the top.
-
-
-Fake threads
-
-For FAKE_THREADS, thr is a global variable and perl schedules threads
-by altering thr in between appropriate ops. The next and prev fields
-of struct thread keep all fake threads on a doubly linked list and
-the next_run and prev_run fields keep all runnable threads on a
-doubly linked list. Mutexes are stubs for FAKE_THREADS. Condition
-variables are implemented as a list of waiting threads.
-
-
-Mutexes and condition variables
-
-The API is via macros MUTEX_{INIT,LOCK,UNLOCK,DESTROY} and
-COND_{INIT,WAIT,SIGNAL,BROADCAST,DESTROY}. For POSIX threads,
-perl mutexes and condition variables correspond to POSIX ones.
-For FAKE_THREADS, mutexes are stubs and condition variables are
-implmented as lists of waiting threads. For FAKE_THREADS, a thread
-waits on a condition variable by removing itself from the runnable
-list, calling SCHEDULE to change thr to the next appropriate
-runnable thread and returning op (i.e. the new threads next op).
-This means that fake threads can only block while in PP code.
-A PP function which contains a COND_WAIT must be prepared to
-handle such restarts and can use the field "private" of struct
-thread to record its state. For fake threads, COND_SIGNAL and
-COND_BROADCAST work by putting back all the threads on the
-condition variables list into the run queue. Note that a mutex
-must *not* be held while returning from a PP function.
-
-Perl locks are a condpair_t structure (a triple of a mutex, a
-condtion variable and an owner thread field) attached by 'm'
-magic to any SV. pp_lock locks such an object by waiting on the
-condition variable until the owner field is zero and then setting
-the owner field to its own thread pointer. The lock is recursive
-so if the owner field already matches the current thread then
-pp_lock returns straight away. If the owner field has to be filled
-in then unlock_condpair is queued as an end-of-block destructor and
-that function zeroes out the owner field, releasing the lock.
-
-
 Building
 
 Omit the -e from your ./Configure arguments. For example, use
@@ -114,10 +55,10 @@ Building the Thread extension
 
 Build it away from the perl tree in the usual way. Set your PATH
 environment variable to have your perl build directory first and
-set PERL5LIB to be your/build/directory/lib (without those, I had
-problems where the config information from the ordinary perl on
-the system would end up in the Makefile). Then
-    perl Makefile.PL
+set PERL5LIB to be /your/perl/build/directory/lib (without those,
+I had problems where the config information from the ordinary perl
+on the system would end up in the Makefile). Then
+    perl Makefile.PL PERL_SRC=/your/perl/build/directory
     make
 On Digital UNIX, you'll probably have to fix the "PERL = 0" and
 "FULLPERL = 0" lines in the generated Makefile as for DynaLoader.
@@ -143,6 +84,11 @@ manually.
 
 Bugs
 
+* Thread states (DETACHED, JOINED etc.) and perl's idea of what's
+  in scope and out of scope aren't properly integrated. Expect
+  segaults and hangs when thread objects whose threads have ended
+  go out of scope (e.g. at program exit).
+
 * cond.t hasn't been redone since condition variable changed.
 
 * FAKE_THREADS should produce a working perl but the Thread
@@ -152,13 +98,72 @@ extension won't build with it yet.
 of each thread because it causes refcount problems that I
 haven't tracked down yet) and there are very probably others too.
 
-* The new synchronised subs design isn't done yet. 
-
 * There are still races where bugs show up under contention.
 
+* Need to document "lock", Thread.pm, Queue.pm, ...
+
 * Plenty of others
 
 
+Background
+
+Some old globals (e.g. stack_sp, op) and some old per-interpreter
+variables (e.g. tmps_stack, cxstack) move into struct thread.
+All fields of struct thread (apart from a few only applicable to
+FAKE_THREADS) are of the form Tfoo. For example, stack_sp becomes
+the field Tstack_sp of struct thread. For those fields which moved
+from original perl, thread.h does
+    #define foo (thr->Tfoo)
+This means that all functions in perl which need to use one of these
+fields need an (automatic) variable thr which points at the current
+thread's struct thread. For pp_foo functions, it is passed around as
+an argument, for other functions they do
+    dTHR;
+which declares and initialises thr from thread-specific data
+via pthread_getspecific. If a function fails to compile with an
+error about "no such variable thr", it probably just needs a dTHR
+at the top.
+
+
+Fake threads
+
+For FAKE_THREADS, thr is a global variable and perl schedules threads
+by altering thr in between appropriate ops. The next and prev fields
+of struct thread keep all fake threads on a doubly linked list and
+the next_run and prev_run fields keep all runnable threads on a
+doubly linked list. Mutexes are stubs for FAKE_THREADS. Condition
+variables are implemented as a list of waiting threads.
+
+
+Mutexes and condition variables
+
+The API is via macros MUTEX_{INIT,LOCK,UNLOCK,DESTROY} and
+COND_{INIT,WAIT,SIGNAL,BROADCAST,DESTROY}. For POSIX threads,
+perl mutexes and condition variables correspond to POSIX ones.
+For FAKE_THREADS, mutexes are stubs and condition variables are
+implmented as lists of waiting threads. For FAKE_THREADS, a thread
+waits on a condition variable by removing itself from the runnable
+list, calling SCHEDULE to change thr to the next appropriate
+runnable thread and returning op (i.e. the new threads next op).
+This means that fake threads can only block while in PP code.
+A PP function which contains a COND_WAIT must be prepared to
+handle such restarts and can use the field "private" of struct
+thread to record its state. For fake threads, COND_SIGNAL and
+COND_BROADCAST work by putting back all the threads on the
+condition variables list into the run queue. Note that a mutex
+must *not* be held while returning from a PP function.
+
+Perl locks are a condpair_t structure (a triple of a mutex, a
+condtion variable and an owner thread field) attached by 'm'
+magic to any SV. pp_lock locks such an object by waiting on the
+condition variable until the owner field is zero and then setting
+the owner field to its own thread pointer. The lock is recursive
+so if the owner field already matches the current thread then
+pp_lock returns straight away. If the owner field has to be filled
+in then unlock_condpair is queued as an end-of-block destructor and
+that function zeroes out the owner field, releasing the lock.
+
+
 Malcolm Beattie
 mbeattie@sable.ox.ac.uk
-13 August 1997
+9 September 1997