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