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