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