1 NOTE: This documentation describes the style of threading that was
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
7 by the Win32 port for emulating fork()). As of Perl 5.8.0, ithreads has
8 become the standard threading model for Perl.
10 If you really want the older support for threads described below,
13 sh Configure -Dusethreads -Duse5005threads
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.)
20 The rest of this document only applies to the use5005threads style of
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.
27 ---------------------------------------------------------------------------
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
31 machines. Internal implementation is still subject to changes.
32 It is not recommended for production use at this time.
34 ---------------------------------------------------------------------------
38 If your system is in the following list you should be able to just:
40 ./Configure -Dusethreads -Duse5005threads -des
43 and ignore the rest of this "Building" section. If not, continue
44 from the "Problems" section.
46 * Linux 2.* (with the LinuxThreads library installed:
47 that's the linuxthreads and linuxthreads-devel RPMs
50 * Tru64 UNIX (formerly Digital UNIX formerly DEC OSF/1)
51 (see additional note below)
53 * Solaris 2.* for recentish x (2.5 is OK)
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.
63 * FreeBSD 2.2.8 or newer.
75 ---------------------------------------------------------------------------
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/
84 On platforms that use Configure to build perl, omit the -d from your
85 ./Configure arguments. For example, use:
87 ./Configure -Dusethreads -Duse5005threads
89 When Configure prompts you for ccflags, insert any other arguments in
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
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.
105 Some additional notes (some of these may be obsolete now, other items
106 may be handled automatically):
108 For Digital Unix 4.x:
109 Add -pthread to ccflags
110 Add -pthread to ldflags
111 Add -lpthread -lc_r to lddlflags
113 For some reason, the extra includes for pthreads make Digital UNIX
114 complain fatally about the sbrk() declaration in perl's malloc.c
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
121 For Digital Unix 3.x (Formerly DEC OSF/1):
122 Add -DOLD_PTHREADS_API to ccflags
123 If compiling with the GNU cc compiler, remove -threads from ccflags
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).
130 (This should all be done automatically by the hint file).
131 Add -lpthread to libs
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
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.
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.
147 (This should all be done automatically by the hint file).
148 Change cc to xlc_r or cc_r.
149 Add -DNEED_PTHREAD_INIT to ccflags and cppflags
150 Add -lc_r to libswanted
151 Change -lc in lddflags to be -lpthread -lc_r -lc
154 See README.win32, and the notes at the beginning of win32/Makefile
155 or win32/makefile.mk.
160 When you succeed in compiling and testing ("make test" after your
161 build) a threaded Perl in a platform previously unknown to support
162 threaded perl, please let perlbug@perl.com know about your victory.
163 Explain what you did in painful detail.
165 ---------------------------------------------------------------------------
169 Irix 6.2: See the Irix warning above.
171 LinuxThreads 0.5 has a bug which can cause file descriptor 0 to be
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:
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
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);
188 pthread_manager_request = pthread_manager_reader = -1;
189 /* Update the pid of the main thread */
190 self->p_pid = getpid();
191 ----------------------------- cut here -----------------------------
194 Building the Thread extension
196 The Thread extension is now part of the main perl distribution tree.
197 If you did Configure -Dusethreads -Duse5005threads then it will have been
198 added to the list of extensions automatically.
200 You can try some of the tests with
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.
210 Try running the main perl test suite too. There are known
211 failures for some of the DBM/DB extensions (if their underlying
212 libraries were not compiled to be thread-aware).
214 ---------------------------------------------------------------------------
218 * FAKE_THREADS should produce a working perl but the Thread
219 extension won't build with it yet. (FAKE_THREADS has not been
220 tested at all in recent times.)
222 * There may still be races where bugs show up under contention.
224 ---------------------------------------------------------------------------
228 Use the -DS command-line option to turn on debugging of the
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
233 #if defined(DEBUGGING) && defined(USE_5005THREADS) && defined(__linux__)
234 DEBUG_S(signal(SIGSEGV, (void(*)(int))catch_sigsegv););
237 ---------------------------------------------------------------------------
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.
243 All fields of struct thread which derived from original perl
244 variables have names of the form Tfoo. For example, stack_sp becomes
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
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
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.
269 Mutexes and condition variables
271 The API is via macros MUTEX_{INIT,LOCK,UNLOCK,DESTROY} and
272 COND_{INIT,WAIT,SIGNAL,BROADCAST,DESTROY}.
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
281 are implemented as lists of waiting threads. For FAKE_THREADS, a thread
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.
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.
314 R_JOINABLE ---------------------> R_JOINED >----\
315 | \ pthread_join(t) | ^ |
316 | \ | | join | pthread_join
321 | $t->detach\ pthread_detach |
323 ends| R_DETACHED ends | unlink
332 ZOMBIE ----------------------------> DEAD
333 pthread_join pthread_detach
334 and unlink and unlink
339 mbeattie@sable.ox.ac.uk
340 Last updated: 27 November 1997
342 Configure-related info updated 16 July 1998 by
343 Andy Dougherty <doughera@lafayette.edu>
345 Other minor updates 10 Feb 1999 by
348 More platforms added 26 Jul 1999 by