README.threads

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