From: Malcolm Beattie Date: Tue, 9 Sep 1997 16:33:45 +0000 (+0000) Subject: Update README.threads X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=43fe56beebc72806ffb19652942eb76c3e4dedd7;p=p5sagit%2Fp5-mst-13.2.git Update README.threads p4raw-id: //depot/perl@58 --- diff --git a/README.threads b/README.threads index a60a897..9e7b4d4 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