README.threads

   1 Building
   2
   3 If you want to build with multi-threading support and you are
   4 running Linux 2.x (with the LinuxThreads library installed:
   5 that's the linuxthreads and linuxthreads-devel RPMs for RedHat)
   6 or Digital UNIX 4.x or Solaris 2.x for recentish x (2.5 is OK)
   7 then you should be able to use
   8     ./Configure -Dusethreads -Doptimize=-g -ders
   9     make
  10 and ignore the rest of this "Building" section. If it doesn't
  11 work or you are using another platform which you believe supports
  12 POSIX.1c threads then read on.
  13
  14 Omit the -e from your ./Configure arguments. For example, use
  15     ./Configure -drs
  16 When it offers to let you change config.sh, do so. If you already
  17 have a config.sh then you can edit it and do
  18     ./Configure -S
  19 to propagate the required changes.
  20 In ccflags, insert -DUSE_THREADS (and probably -DDEBUGGING since
  21 that's what I've been building with). Also insert any other
  22 arguments in there that your compiler needs to use POSIX threads.
  23 Change optimize to -g to give you better debugging information.
  24 Include any necessary explicit libraries in libs and change
  25 ldflags if you need any linker flags instead or as well.
  26
  27 More explicitly, for Linux (when using the standard kernel-threads
  28 based LinuxThreads library):
  29     Add -DUSE_THREADS -D_REENTRANT -DDEBUGGING to ccflags and cppflags
  30     Add -lpthread to libs
  31     Change optimize to -g
  32 For Digital Unix 4.x:
  33     Add -pthread -DUSE_THREADS -DDEBUGGING to ccflags
  34     Add -DUSE_THREADS -DDEBUGGING to cppflags
  35     Add -pthread to ldflags
  36     Change optimize to -g
  37     Add -lpthread -lc_r to lddlflags
  38     For some reason, the extra includes for pthreads make Digital UNIX
  39     complain fatally about the sbrk() delcaration in perl's malloc.c
  40     so use the native malloc as follows:
  41     Change usemymalloc to n
  42     Zap mallocobj and mallocsrc (foo='')
  43     Change d_mymalloc to undef
  44 For Solaris, do the same as for Linux above.
  45
  46 Now you can do a
  47     make
  48
  49
  50 O/S specific bugs
  51
  52 Solaris qsort uses a hidden mutex for synchronisation. If you die()
  53 while doing a sort() then the resulting longjmp() leaves the mutex
  54 locked so you get a deadlock the next time you try to sort().
  55
  56 LinuxThreads 0.5 has a bug which can cause file descriptor 0 to be
  57 closed after a fork() leading to many strange symptoms. The
  58 development version of LinuxThreads has this fixed but the following
  59 patch can be applied to 0.5 for now:
  60
  61 ----------------------------- cut here -----------------------------
  62 --- linuxthreads-0.5/pthread.c.ORI      Mon Oct  6 13:55:50 1997
  63 +++ linuxthreads-0.5/pthread.c  Mon Oct  6 13:57:24 1997
  64 @@ -312,8 +312,10 @@
  65    free(pthread_manager_thread_bos);
  66    pthread_manager_thread_bos = pthread_manager_thread_tos = NULL;
  67    /* Close the two ends of the pipe */
  68 -  close(pthread_manager_request);
  69 -  close(pthread_manager_reader);
  70 +  if (pthread_manager_request >= 0) {
  71 +    close(pthread_manager_request);
  72 +    close(pthread_manager_reader);
  73 +  }
  74    pthread_manager_request = pthread_manager_reader = -1;
  75    /* Update the pid of the main thread */
  76    self->p_pid = getpid();
  77 ----------------------------- cut here -----------------------------
  78
  79
  80 Building the Thread extension
  81
  82 The Thread extension is now part of the main perl distribution tree.
  83 If you did Configure -Dusethreads then it will have been added to
  84 the list of extensions automatically.
  85
  86 You can try some of the tests with
  87     cd ext/Thread
  88     perl -Mblib create.t
  89     perl -Mblib join.t
  90     perl -Mblib lock.t
  91     perl -Mblib unsync.t
  92     perl -Mblib unsync2.t
  93     perl -Mblib unsync3.t
  94     perl -Mblib io.t
  95     perl -Mblib queue.t
  96 The io one leaves a thread reading from the keyboard on stdin so
  97 as the ping messages appear you can type lines and see them echoed.
  98
  99 Try running the main perl test suite too. There are known
 100 failures for op/misc test 45 (tries to do local(@_) but @_ is
 101 now lexical) and for some of the DBM/DB extensions (if there
 102 underlying libraries were not compiled to be thread-aware).
 103 may or may not work.
 104
 105
 106 Bugs
 107
 108 * cond.t hasn't been redone since condition variable changed.
 109
 110 * FAKE_THREADS should produce a working perl but the Thread
 111 extension won't build with it yet.
 112
 113 * There's a known memory leak (curstack isn't freed at the end
 114 of each thread because it causes refcount problems that I
 115 haven't tracked down yet) and there are very probably others too.
 116
 117 * There may still be races where bugs show up under contention.
 118
 119 * Need to document "lock", Thread.pm, Queue.pm, ...
 120
 121 * Plenty of others
 122
 123
 124 Debugging
 125
 126 Use the -DL command-line option to turn on debugging of the
 127 multi-threading code. Under Linux, that also turns on a quick
 128 hack I did to grab a bit of extra information from segfaults.
 129 If you have a fancier gdb/threads setup than I do then you'll
 130 have to delete the lines in perl.c which say
 131     #if defined(DEBUGGING) && defined(USE_THREADS) && defined(__linux__)
 132         DEBUG_L(signal(SIGSEGV, (void(*)(int))catch_sigsegv););
 133     #endif
 134
 135
 136 Background
 137
 138 Some old globals (e.g. stack_sp, op) and some old per-interpreter
 139 variables (e.g. tmps_stack, cxstack) move into struct thread.
 140 All fields of struct thread which derived from original perl
 141 variables have names of the form Tfoo. For example, stack_sp becomes
 142 the field Tstack_sp of struct thread. For those fields which moved
 143 from original perl, thread.h does
 144     #define foo (thr->Tfoo)
 145 This means that all functions in perl which need to use one of these
 146 fields need an (automatic) variable thr which points at the current
 147 thread's struct thread. For pp_foo functions, it is passed around as
 148 an argument, for other functions they do
 149     dTHR;
 150 which declares and initialises thr from thread-specific data
 151 via pthread_getspecific. If a function fails to compile with an
 152 error about "no such variable thr", it probably just needs a dTHR
 153 at the top.
 154
 155
 156 Fake threads
 157
 158 For FAKE_THREADS, thr is a global variable and perl schedules threads
 159 by altering thr in between appropriate ops. The next and prev fields
 160 of struct thread keep all fake threads on a doubly linked list and
 161 the next_run and prev_run fields keep all runnable threads on a
 162 doubly linked list. Mutexes are stubs for FAKE_THREADS. Condition
 163 variables are implemented as a list of waiting threads.
 164
 165
 166 Mutexes and condition variables
 167
 168 The API is via macros MUTEX_{INIT,LOCK,UNLOCK,DESTROY} and
 169 COND_{INIT,WAIT,SIGNAL,BROADCAST,DESTROY}.
 170
 171 A mutex is only required to be a simple, fast mutex (e.g. it does not
 172 have to be recursive). It is only ever held across very short pieces
 173 of code. Condition variables are only ever signalled/broadcast while
 174 their associated mutex is held. (This constraint simplifies the
 175 implementation of condition variables in certain porting situations.)
 176 For POSIX threads, perl mutexes and condition variables correspond to
 177 POSIX ones.  For FAKE_THREADS, mutexes are stubs and condition variables
 178 are implmented as lists of waiting threads. For FAKE_THREADS, a thread
 179 waits on a condition variable by removing itself from the runnable
 180 list, calling SCHEDULE to change thr to the next appropriate
 181 runnable thread and returning op (i.e. the new threads next op).
 182 This means that fake threads can only block while in PP code.
 183 A PP function which contains a COND_WAIT must be prepared to
 184 handle such restarts and can use the field "private" of struct
 185 thread to record its state. For fake threads, COND_SIGNAL and
 186 COND_BROADCAST work by putting back all the threads on the
 187 condition variables list into the run queue. Note that a mutex
 188 must *not* be held while returning from a PP function.
 189
 190 Perl locks and condition variables are both implemented as a
 191 condpair_t structure, containing a mutex, an "owner" condition
 192 variable, an owner thread field and another condition variable).
 193 The structure is attached by 'm' magic to any SV. pp_lock locks
 194 such an object by waiting on the ownercond condition variable until
 195 the owner field is zero and then setting the owner field to its own
 196 thread pointer. The lock is semantically recursive so if the owner
 197 field already matches the current thread then pp_lock returns
 198 straight away. If the owner field has to be filled in then
 199 unlock_condpair is queued as an end-of-block destructor and
 200 that function zeroes out the owner field and signals the ownercond
 201 condition variable, thus waking up any other thread that wants to
 202 lock it. When used as a condition variable, the condpair is locked
 203 (involving the above wait-for-ownership and setting the owner field)
 204 and the spare condition variable field is used for waiting on.
 205
 206
 207 Thread states
 208
 209
 210               $t->join
 211 R_JOINABLE ---------------------> R_JOINED >----\
 212     |      \  pthread_join(t)         |  ^      |
 213     |       \                         |  | join | pthread_join
 214     |        \                        |  |      |
 215     |         \                       |  \------/
 216     |          \                      |
 217     |           \                     |
 218     |  $t->detach\ pthread_detach     |
 219     |            _\|                  |
 220 ends|             R_DETACHED     ends | unlink
 221     |                       \         |
 222     |                   ends \ unlink |
 223     |                         \       |
 224     |                          \      |
 225     |                           \     |
 226     |                            \    |
 227     |                             \   |
 228     V    join          detach     _\| V
 229 ZOMBIE ----------------------------> DEAD
 230        pthread_join   pthread_detach
 231        and unlink     and unlink
 232
 233
 234
 235 Malcolm Beattie
 236 mbeattie@sable.ox.ac.uk
 237 6 November 1997