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