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