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