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