README.threads

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