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