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