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