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