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