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