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