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