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