Commit | Line | Data |
---|---|---|
a2dab6bc GS |
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 | --------------------------------------------------------------------------- | |
99ed61e6 | 15 | |
a2dab6bc GS |
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 | |
99ed61e6 GS |
18 | machines. Internal implementation is still subject to changes. |
19 | It is not recommended for production use at this time. | |
20 | ||
effcca5c JH |
21 | --------------------------------------------------------------------------- |
22 | ||
72aaf631 MB |
23 | Building |
24 | ||
effcca5c | 25 | If your system is in the following list you should be able to just: |
e2198c6b | 26 | |
a2dab6bc | 27 | ./Configure -Dusethreads -Duse5005threads -des |
effcca5c | 28 | make |
69ce17de | 29 | |
effcca5c JH |
30 | and ignore the rest of this "Building" section. If not, continue |
31 | from the "Problems" section. | |
69ce17de | 32 | |
effcca5c JH |
33 | * Linux 2.* (with the LinuxThreads library installed: |
34 | that's the linuxthreads and linuxthreads-devel RPMs | |
35 | for RedHat) | |
3cec1e99 | 36 | |
effcca5c JH |
37 | * Tru64 UNIX (formerly Digital UNIX formerly DEC OSF/1) |
38 | (see additional note below) | |
69ce17de | 39 | |
effcca5c | 40 | * Solaris 2.* for recentish x (2.5 is OK) |
69ce17de | 41 | |
effcca5c JH |
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. | |
e2198c6b | 47 | |
effcca5c JH |
48 | * AIX 4.1.5 or newer. |
49 | ||
50 | * FreeBSD 2.2.8 or newer. | |
51 | ||
52 | * OpenBSD | |
53 | ||
f556e5b9 | 54 | * NeXTstep, OpenStep |
e2198c6b | 55 | |
effcca5c JH |
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 | ||
e5e20432 JH |
71 | On platforms that use Configure to build perl, omit the -d from your |
72 | ./Configure arguments. For example, use: | |
e2198c6b | 73 | |
a2dab6bc | 74 | ./Configure -Dusethreads -Duse5005threads |
e2198c6b AD |
75 | |
76 | When Configure prompts you for ccflags, insert any other arguments in | |
e5e20432 JH |
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 | |
effcca5c | 86 | of -lc. |
e2198c6b AD |
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 | ||
72aaf631 | 95 | For Digital Unix 4.x: |
e2198c6b | 96 | Add -pthread to ccflags |
72aaf631 | 97 | Add -pthread to ldflags |
d81a1b93 | 98 | Add -lpthread -lc_r to lddlflags |
e2198c6b | 99 | |
72aaf631 MB |
100 | For some reason, the extra includes for pthreads make Digital UNIX |
101 | complain fatally about the sbrk() delcaration in perl's malloc.c | |
e2198c6b AD |
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 | ||
3cec1e99 GS |
108 | For Digital Unix 3.x (Formerly DEC OSF/1): |
109 | Add -DOLD_PTHREADS_API to ccflags | |
effcca5c | 110 | If compiling with the GNU cc compiler, remove -threads from ccflags |
3cec1e99 GS |
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 | ||
eb1cfdd6 | 116 | For IRIX: |
e2198c6b | 117 | (This should all be done automatically by the hint file). |
eb1cfdd6 | 118 | Add -lpthread to libs |
eb1cfdd6 MB |
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 | |
69ce17de MB |
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 | ||
eb1cfdd6 MB |
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. | |
effcca5c | 132 | |
ce637636 | 133 | For AIX: |
e2198c6b | 134 | (This should all be done automatically by the hint file). |
ce637636 | 135 | Change cc to xlc_r or cc_r. |
e2198c6b | 136 | Add -DNEED_PTHREAD_INIT to ccflags and cppflags |
ce637636 JH |
137 | Add -lc_r to libswanted |
138 | Change -lc in lddflags to be -lpthread -lc_r -lc | |
72aaf631 | 139 | |
99ed61e6 GS |
140 | For Win32: |
141 | See README.win32, and the notes at the beginning of win32/Makefile | |
142 | or win32/makefile.mk. | |
143 | ||
72aaf631 | 144 | Now you can do a |
d81a1b93 MB |
145 | make |
146 | ||
effcca5c JH |
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 | --------------------------------------------------------------------------- | |
72aaf631 | 153 | |
5756a3ac MB |
154 | O/S specific bugs |
155 | ||
e2198c6b | 156 | Irix 6.2: See the Irix warning above. |
5756a3ac MB |
157 | |
158 | LinuxThreads 0.5 has a bug which can cause file descriptor 0 to be | |
69ce17de MB |
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: | |
5756a3ac MB |
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 | ||
72aaf631 MB |
181 | Building the Thread extension |
182 | ||
5756a3ac | 183 | The Thread extension is now part of the main perl distribution tree. |
a2dab6bc GS |
184 | If you did Configure -Dusethreads -Duse5005threads then it will have been |
185 | added to the list of extensions automatically. | |
72aaf631 | 186 | |
5756a3ac MB |
187 | You can try some of the tests with |
188 | cd ext/Thread | |
69ce17de MB |
189 | perl create.t |
190 | perl join.t | |
191 | perl lock.t | |
192 | perl io.t | |
193 | etc. | |
72aaf631 MB |
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 | |
69ce17de MB |
198 | failures for some of the DBM/DB extensions (if their underlying |
199 | libraries were not compiled to be thread-aware). | |
72aaf631 | 200 | |
effcca5c | 201 | --------------------------------------------------------------------------- |
72aaf631 MB |
202 | |
203 | Bugs | |
204 | ||
72aaf631 | 205 | * FAKE_THREADS should produce a working perl but the Thread |
99ed61e6 GS |
206 | extension won't build with it yet. (FAKE_THREADS has not been |
207 | tested at all in recent times.) | |
72aaf631 | 208 | |
5756a3ac | 209 | * There may still be races where bugs show up under contention. |
72aaf631 | 210 | |
effcca5c | 211 | --------------------------------------------------------------------------- |
72aaf631 | 212 | |
1304aa9d MB |
213 | Debugging |
214 | ||
8b73bbec | 215 | Use the -DS command-line option to turn on debugging of the |
1304aa9d MB |
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__) | |
8b73bbec | 221 | DEBUG_S(signal(SIGSEGV, (void(*)(int))catch_sigsegv);); |
1304aa9d MB |
222 | #endif |
223 | ||
effcca5c | 224 | --------------------------------------------------------------------------- |
1304aa9d | 225 | |
43fe56be MB |
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. | |
5756a3ac MB |
230 | All fields of struct thread which derived from original perl |
231 | variables have names of the form Tfoo. For example, stack_sp becomes | |
43fe56be MB |
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 | |
5756a3ac MB |
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 | |
43fe56be MB |
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 | ||
c7848ba1 MB |
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 | ||
43fe56be MB |
323 | |
324 | ||
72aaf631 MB |
325 | Malcolm Beattie |
326 | mbeattie@sable.ox.ac.uk | |
69ce17de | 327 | Last updated: 27 November 1997 |
e2198c6b AD |
328 | |
329 | Configure-related info updated 16 July 1998 by | |
330 | Andy Dougherty <doughera@lafayette.edu> | |
99ed61e6 GS |
331 | |
332 | Other minor updates 10 Feb 1999 by | |
333 | Gurusamy Sarathy | |
effcca5c JH |
334 | |
335 | More platforms added 26 Jul 1999 by | |
336 | Jarkko Hietaniemi |