Commit | Line | Data |
---|---|---|
72aaf631 MB |
1 | Building |
2 | ||
d81a1b93 | 3 | If you want to build with multi-threading support and you are |
69ce17de MB |
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 | ||
d81a1b93 MB |
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 | ||
72aaf631 MB |
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 | |
d81a1b93 | 47 | Add -lpthread -lc_r to lddlflags |
72aaf631 MB |
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 | |
d81a1b93 | 54 | For Solaris, do the same as for Linux above. |
eb1cfdd6 MB |
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 | |
69ce17de MB |
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 | ||
eb1cfdd6 MB |
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. | |
ce637636 JH |
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 | |
72aaf631 MB |
79 | |
80 | Now you can do a | |
d81a1b93 MB |
81 | make |
82 | ||
72aaf631 | 83 | |
5756a3ac MB |
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 | |
69ce17de MB |
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: | |
5756a3ac MB |
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 | ||
72aaf631 MB |
113 | Building the Thread extension |
114 | ||
5756a3ac MB |
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. | |
72aaf631 | 118 | |
5756a3ac MB |
119 | You can try some of the tests with |
120 | cd ext/Thread | |
69ce17de MB |
121 | perl create.t |
122 | perl join.t | |
123 | perl lock.t | |
124 | perl io.t | |
125 | etc. | |
72aaf631 MB |
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 | |
69ce17de MB |
130 | failures for some of the DBM/DB extensions (if their underlying |
131 | libraries were not compiled to be thread-aware). | |
72aaf631 MB |
132 | |
133 | ||
134 | Bugs | |
135 | ||
72aaf631 MB |
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 | ||
5756a3ac | 143 | * There may still be races where bugs show up under contention. |
72aaf631 | 144 | |
43fe56be MB |
145 | * Need to document "lock", Thread.pm, Queue.pm, ... |
146 | ||
72aaf631 | 147 | |
1304aa9d MB |
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 | ||
43fe56be MB |
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. | |
5756a3ac MB |
164 | All fields of struct thread which derived from original perl |
165 | variables have names of the form Tfoo. For example, stack_sp becomes | |
43fe56be MB |
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 | |
5756a3ac MB |
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 | |
43fe56be MB |
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 | ||
c7848ba1 MB |
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 | ||
43fe56be MB |
257 | |
258 | ||
72aaf631 MB |
259 | Malcolm Beattie |
260 | mbeattie@sable.ox.ac.uk | |
69ce17de | 261 | Last updated: 27 November 1997 |