$VERSION "a5" doesn't quite work.
[p5sagit/p5-mst-13.2.git] / README.threads
CommitLineData
a2dab6bc 1NOTE: This documentation describes the style of threading that was
2available in 5.005. Perl v5.6 also has the early beginnings of
3interpreter-based threads support (which is what will be enabled by
4default when you simply ask for -Dusethreads). However, be advised
5that interpreter threads cannot as yet be created from the Perl level
6yet. If you're looking to create threads from within Perl, chances
7are you _don't_ want interpreter threads, but want the older support
8for threads described below, enabled with:
9
10 sh Configure -Dusethreads -Duse5005threads
11
12The rest of this document only applies to the use5005threads style of
13threads.
14---------------------------------------------------------------------------
99ed61e6 15
a2dab6bc 16Support for threading is still in the highly experimental stages. There
17are known race conditions that show up under high contention on SMP
99ed61e6 18machines. Internal implementation is still subject to changes.
19It is not recommended for production use at this time.
20
effcca5c 21---------------------------------------------------------------------------
22
72aaf631 23Building
24
effcca5c 25If 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 30and ignore the rest of this "Building" section. If not, continue
31from the "Problems" section.
69ce17de 32
effcca5c 33 * Linux 2.* (with the LinuxThreads library installed:
34 that's the linuxthreads and linuxthreads-devel RPMs
35 for RedHat)
3cec1e99 36
effcca5c 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 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 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 56 * OS/2
57
58 * DOS DJGPP
59
60 * VM/ESA
61
62---------------------------------------------------------------------------
63
64Problems
65
66If the simple way doesn't work or you are using another platform which
67you believe supports POSIX.1c threads then read on. Additional
68information may be in a platform-specific "hints" file in the hints/
69subdirectory.
70
e5e20432 71On 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 75
76When Configure prompts you for ccflags, insert any other arguments in
e5e20432 77there that your compiler needs to use POSIX threads (-D_REENTRANT,
78-pthreads, -threads, -pthread, -thread, are good guesses). When
79Configure prompts you for linking flags, include any flags required
80for threading (usually nothing special is required here). Finally,
81when Configure prompts you for libraries, include any necessary
82libraries (e.g. -lpthread). Pay attention to the order of libraries.
83It is probably necessary to specify your threading library *before*
84your 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 86of -lc.
e2198c6b 87
88Once you have specified all your compiler flags, you can have Configure
89accept all the defaults for the remainder of the session by typing &-d
90at any Configure prompt.
91
92Some additional notes (some of these may be obsolete now, other items
93may be handled automatically):
94
72aaf631 95For 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 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 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 108For 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 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 116For IRIX:
e2198c6b 117 (This should all be done automatically by the hint file).
eb1cfdd6 118 Add -lpthread to libs
eb1cfdd6 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 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 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 133For 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 137 Add -lc_r to libswanted
138 Change -lc in lddflags to be -lpthread -lc_r -lc
72aaf631 139
99ed61e6 140For Win32:
141 See README.win32, and the notes at the beginning of win32/Makefile
142 or win32/makefile.mk.
143
72aaf631 144Now you can do a
d81a1b93 145 make
146
effcca5c 147When you succeed in compiling and testing ("make test" after your
148build) a threaded Perl in a platform previosuly unknown to support
149threaded perl, please let perlbug@perl.com know about your victory.
150Explain what you did in painful detail.
151
152---------------------------------------------------------------------------
72aaf631 153
5756a3ac 154O/S specific bugs
155
e2198c6b 156Irix 6.2: See the Irix warning above.
5756a3ac 157
158LinuxThreads 0.5 has a bug which can cause file descriptor 0 to be
69ce17de 159closed after a fork() leading to many strange symptoms. Version 0.6
160has this fixed but the following patch can be applied to 0.5 for now:
5756a3ac 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 181Building the Thread extension
182
5756a3ac 183The Thread extension is now part of the main perl distribution tree.
a2dab6bc 184If you did Configure -Dusethreads -Duse5005threads then it will have been
185added to the list of extensions automatically.
72aaf631 186
5756a3ac 187You can try some of the tests with
188 cd ext/Thread
69ce17de 189 perl create.t
190 perl join.t
191 perl lock.t
192 perl io.t
193etc.
72aaf631 194The io one leaves a thread reading from the keyboard on stdin so
195as the ping messages appear you can type lines and see them echoed.
196
197Try running the main perl test suite too. There are known
69ce17de 198failures for some of the DBM/DB extensions (if their underlying
199libraries were not compiled to be thread-aware).
72aaf631 200
effcca5c 201---------------------------------------------------------------------------
72aaf631 202
203Bugs
204
72aaf631 205* FAKE_THREADS should produce a working perl but the Thread
99ed61e6 206extension won't build with it yet. (FAKE_THREADS has not been
207tested 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 213Debugging
214
8b73bbec 215Use the -DS command-line option to turn on debugging of the
1304aa9d 216multi-threading code. Under Linux, that also turns on a quick
217hack I did to grab a bit of extra information from segfaults.
218If you have a fancier gdb/threads setup than I do then you'll
219have to delete the lines in perl.c which say
4d1ff10f 220 #if defined(DEBUGGING) && defined(USE_5005THREADS) && defined(__linux__)
8b73bbec 221 DEBUG_S(signal(SIGSEGV, (void(*)(int))catch_sigsegv););
1304aa9d 222 #endif
223
effcca5c 224---------------------------------------------------------------------------
1304aa9d 225
43fe56be 226Background
227
228Some old globals (e.g. stack_sp, op) and some old per-interpreter
229variables (e.g. tmps_stack, cxstack) move into struct thread.
5756a3ac 230All fields of struct thread which derived from original perl
231variables have names of the form Tfoo. For example, stack_sp becomes
43fe56be 232the field Tstack_sp of struct thread. For those fields which moved
233from original perl, thread.h does
234 #define foo (thr->Tfoo)
235This means that all functions in perl which need to use one of these
236fields need an (automatic) variable thr which points at the current
237thread's struct thread. For pp_foo functions, it is passed around as
238an argument, for other functions they do
239 dTHR;
240which declares and initialises thr from thread-specific data
241via pthread_getspecific. If a function fails to compile with an
242error about "no such variable thr", it probably just needs a dTHR
243at the top.
244
245
246Fake threads
247
248For FAKE_THREADS, thr is a global variable and perl schedules threads
249by altering thr in between appropriate ops. The next and prev fields
250of struct thread keep all fake threads on a doubly linked list and
251the next_run and prev_run fields keep all runnable threads on a
252doubly linked list. Mutexes are stubs for FAKE_THREADS. Condition
253variables are implemented as a list of waiting threads.
254
255
256Mutexes and condition variables
257
258The API is via macros MUTEX_{INIT,LOCK,UNLOCK,DESTROY} and
5756a3ac 259COND_{INIT,WAIT,SIGNAL,BROADCAST,DESTROY}.
260
261A mutex is only required to be a simple, fast mutex (e.g. it does not
262have to be recursive). It is only ever held across very short pieces
263of code. Condition variables are only ever signalled/broadcast while
264their associated mutex is held. (This constraint simplifies the
265implementation of condition variables in certain porting situations.)
266For POSIX threads, perl mutexes and condition variables correspond to
267POSIX ones. For FAKE_THREADS, mutexes are stubs and condition variables
268are implmented as lists of waiting threads. For FAKE_THREADS, a thread
43fe56be 269waits on a condition variable by removing itself from the runnable
270list, calling SCHEDULE to change thr to the next appropriate
271runnable thread and returning op (i.e. the new threads next op).
272This means that fake threads can only block while in PP code.
273A PP function which contains a COND_WAIT must be prepared to
274handle such restarts and can use the field "private" of struct
275thread to record its state. For fake threads, COND_SIGNAL and
276COND_BROADCAST work by putting back all the threads on the
277condition variables list into the run queue. Note that a mutex
278must *not* be held while returning from a PP function.
279
c7848ba1 280Perl locks and condition variables are both implemented as a
281condpair_t structure, containing a mutex, an "owner" condition
282variable, an owner thread field and another condition variable).
283The structure is attached by 'm' magic to any SV. pp_lock locks
284such an object by waiting on the ownercond condition variable until
285the owner field is zero and then setting the owner field to its own
286thread pointer. The lock is semantically recursive so if the owner
287field already matches the current thread then pp_lock returns
288straight away. If the owner field has to be filled in then
289unlock_condpair is queued as an end-of-block destructor and
290that function zeroes out the owner field and signals the ownercond
291condition variable, thus waking up any other thread that wants to
292lock it. When used as a condition variable, the condpair is locked
293(involving the above wait-for-ownership and setting the owner field)
294and the spare condition variable field is used for waiting on.
295
296
297Thread states
298
299
300 $t->join
301R_JOINABLE ---------------------> R_JOINED >----\
302 | \ pthread_join(t) | ^ |
303 | \ | | join | pthread_join
304 | \ | | |
305 | \ | \------/
306 | \ |
307 | \ |
308 | $t->detach\ pthread_detach |
309 | _\| |
310ends| R_DETACHED ends | unlink
311 | \ |
312 | ends \ unlink |
313 | \ |
314 | \ |
315 | \ |
316 | \ |
317 | \ |
318 V join detach _\| V
319ZOMBIE ----------------------------> DEAD
320 pthread_join pthread_detach
321 and unlink and unlink
322
43fe56be 323
324
72aaf631 325Malcolm Beattie
326mbeattie@sable.ox.ac.uk
69ce17de 327Last updated: 27 November 1997
e2198c6b 328
329Configure-related info updated 16 July 1998 by
330Andy Dougherty <doughera@lafayette.edu>
99ed61e6 331
332Other minor updates 10 Feb 1999 by
333Gurusamy Sarathy
effcca5c 334
335More platforms added 26 Jul 1999 by
336Jarkko Hietaniemi