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