Many updates, in particular w.r.t. debugging.
[kopensolaris-gnu/glibc.git] / linuxthreads / FAQ.html
1 <HTML>
2 <HEAD>
3 <TITLE>LinuxThreads Frequently Asked Questions</TITLE>
4 </HEAD>
5 <BODY>
6 <H1 ALIGN=center>LinuxThreads Frequently Asked Questions <BR>
7                  (with answers)</H1>
8 <H2 ALIGN=center>[For LinuxThreads version 0.8]</H2>
9
10 <HR><P>
11
12 <A HREF="#A">A. The big picture</A><BR>
13 <A HREF="#B">B. Getting more information</A><BR>
14 <A HREF="#C">C. Issues related to the C library</A><BR>
15 <A HREF="#D">D. Problems, weird behaviors, potential bugs</A><BR>
16 <A HREF="#E">E. Missing functions, wrong types, etc</A><BR>
17 <A HREF="#F">F. C++ issues</A><BR>
18 <A HREF="#G">G. Debugging LinuxThreads programs</A><BR>
19 <A HREF="#H">H. Compiling multithreaded code; errno madness</A><BR>
20 <A HREF="#I">I. X-Windows and other libraries</A><BR>
21 <A HREF="#J">J. Signals and threads</A><BR>
22 <A HREF="#K">K. Internals of LinuxThreads</A><P>
23
24 <HR>
25 <P>
26
27 <H2><A NAME="A">A. The big picture</A></H2>
28
29 <H4><A NAME="A.1">A.1: What is LinuxThreads?</A></H4>
30
31 LinuxThreads is a Linux library for multi-threaded programming.
32 It implements the Posix 1003.1c API (Application Programming
33 Interface) for threads.  It runs on any Linux system with kernel 2.0.0
34 or more recent, and a suitable C library (see section <A HREF="C">C</A>).
35 <P>
36
37 <H4><A NAME="A.2">A.2: What are threads?</A></H4>
38
39 A thread is a sequential flow of control through a program.
40 Multi-threaded programming is, thus, a form of parallel programming
41 where several threads of control are executing concurrently in the
42 program.  All threads execute in the same memory space, and can
43 therefore work concurrently on shared data.<P>
44
45 Multi-threaded programming differs from Unix-style multi-processing in
46 that all threads share the same memory space (and a few other system
47 resources, such as file descriptors), instead of running in their own
48 memory space as is the case with Unix processes.<P>
49
50 Threads are useful for two reasons.  First, they allow a program to
51 exploit multi-processor machines: the threads can run in parallel on
52 several processors, allowing a single program to divide its work
53 between several processors, thus running faster than a single-threaded
54 program, which runs on only one processor at a time.  Second, some
55 programs are best expressed as several threads of control that
56 communicate together, rather than as one big monolithic sequential
57 program.  Examples include server programs, overlapping asynchronous
58 I/O, and graphical user interfaces.<P>
59
60 <H4><A NAME="A.3">A.3: What is POSIX 1003.1c?</A></H4>
61
62 It's an API for multi-threaded programming standardized by IEEE as
63 part of the POSIX standards.  Most Unix vendors have endorsed the
64 POSIX 1003.1c standard.  Implementations of the 1003.1c API are
65 already available under Sun Solaris 2.5, Digital Unix 4.0,
66 Silicon Graphics IRIX 6, and should soon be available from other
67 vendors such as IBM and HP.  More generally, the 1003.1c API is
68 replacing relatively quickly the proprietary threads library that were
69 developed previously under Unix, such as Mach cthreads, Solaris
70 threads, and IRIX sprocs.  Thus, multithreaded programs using the
71 1003.1c API are likely to run unchanged on a wide variety of Unix
72 platforms.<P>
73
74 <H4><A NAME="A.4">A.4: What is the status of LinuxThreads?</A></H4>
75
76 In short, it's not completely finished (hence the version numbers in
77 0.<I>x</I>), but what is done is pretty mature.
78 LinuxThreads implements almost all of Posix 1003.1c, as well as a few
79 extensions.  The only part of LinuxThreads that does not conform yet
80 to Posix is signal handling (see section <A HREF="#J">J</A>).  Apart
81 from the signal stuff, all the Posix 1003.1c base functionality is
82 provided and conforms to the standard (to the best of my knowledge).
83 The signal stuff is hard to get right, at least without special kernel
84 support, and while I'm definitely looking at ways to implement the
85 Posix behavior for signals, this might take a long time before it's
86 completed.<P>
87
88 <H4><A NAME="A.5">A.5: How stable is LinuxThreads?</A></H4>
89
90 The basic functionality (thread creation and termination, mutexes,
91 conditions, semaphores) is very stable.  Several industrial-strength
92 programs, such as the AOL multithreaded Web server, use LinuxThreads
93 and seem quite happy about it.  There are some rough edges in
94 the LinuxThreads / C library interface, at least with libc 5, but most
95 of these rough edges are fixed in glibc 2, which should soon become
96 the standard C library for Linux distributions (see section <A
97 HREF="#C">C</A>). <P>
98
99 <HR>
100 <P>
101
102 <H2><A NAME="B">B.  Getting more information</A></H2>
103
104 <H4><A NAME="B.1">B.1: What are good books and other sources of
105 information on POSIX threads?</A></H4>
106
107 The FAQ for comp.programming.threads lists several books:
108 <A HREF="http://www.serpentine.com/~bos/threads-faq/">http://www.serpentine.com/~bos/threads-faq/</A>.<P>
109
110 There are also some online tutorials. Follow the links from the
111 LinuxThreads web page:
112 <A HREF="http://pauillac.inria.fr/~xleroy/linuxthreads">http://pauillac.inria.fr/~xleroy/linuxthreads</A>.<P>
113
114 <H4><A NAME="B.2">B.2: I'd like to be informed of future developments on
115 LinuxThreads. Is there a mailing list for this purpose?</A></H4>
116
117 I post LinuxThreads-related announcements on the newsgroup
118 <A HREF="news:comp.os.linux.announce">comp.os.linux.announce</A>,
119 and also on the mailing list
120 <code>linux-threads@magenet.com</code>.
121 You can subscribe to the latter by writing
122 <A HREF="mailto:majordomo@magenet.com">majordomo@magenet.com</A>.<P>
123
124 <H4><A NAME="B.3">B.3: What are good places for discussing
125 LinuxThreads?</A></H4>
126
127 For questions about programming with POSIX threads in general, use
128 the newsgroup
129 <A HREF="news:comp.programming.threads">comp.programming.threads</A>.
130 Be sure you read the
131 <A HREF="http://www.serpentine.com/~bos/threads-faq/">FAQ</A>
132 for this group before you post.<P>
133
134 For Linux-specific questions, use
135 <A
136 HREF="news:comp.os.linux.development.apps">comp.os.linux.development.apps</A>
137 and <A
138 HREF="news:comp.os.linux.development.kernel">comp.os.linux.development.kernel</A>.
139 The latter is especially appropriate for questions relative to the
140 interface between the kernel and LinuxThreads.<P>
141
142 Very specific LinuxThreads questions, and in particular everything
143 that looks like a potential bug in LinuxThreads, should be mailed
144 directly to me (<code>Xavier.Leroy@inria.fr</code>).  Before mailing
145 me, make sure that your question is not answered in this FAQ.<P>
146
147 <H4><A NAME="B.4">B.4: I'd like to read the POSIX 1003.1c standard. Is
148 it available online?</A></H4>
149
150 Unfortunately, no.  POSIX standards are copyrighted by IEEE, and
151 IEEE does not distribute them freely.  You can buy paper copies from
152 IEEE, but the price is fairly high ($120 or so). If you disagree with
153 this policy and you're an IEEE member, be sure to let them know.<P>
154
155 On the other hand, you probably don't want to read the standard.  It's
156 very hard to read, written in standard-ese, and targeted to
157 implementors who already know threads inside-out.  A good book on
158 POSIX threads provides the same information in a much more readable form.
159 I can personally recommend Dave Butenhof's book, <CITE>Programming
160 with POSIX threads</CITE> (Addison-Wesley). Butenhof was part of the
161 POSIX committee and also designed the Digital Unix implementations of
162 POSIX threads, and it shows.<P>
163
164 Another good source of information is the X/Open Group Single Unix
165 specification which is available both
166 <A HREF="http://www.rdg.opengroup.org/onlinepubs/7908799/index.html">on-line</A>
167 and as a
168 <A HREF="http://www.UNIX-systems.org/gosolo2/">book and CD/ROM</A>.
169 That specification includes pretty much all the POSIX standards,
170 including 1003.1c, with some extensions and clarifications.<P>
171
172 <HR>
173 <P>
174
175 <H2><A NAME="C">C.  Issues related to the C library</A></H2>
176
177 <H4><A NAME="C.1">C.1: Which version of the C library should I use
178 with LinuxThreads?</A></H4>
179
180 The best choice by far is glibc 2, a.k.a. libc 6.  It offers very good
181 support for multi-threading, and LinuxThreads has been closely
182 integrated with glibc 2.  The glibc 2 distribution contains the
183 sources of a specially adapted version of LinuxThreads.<P>
184
185 glibc 2 comes preinstalled as the default C library on several Linux
186 distributions, such as RedHat 5.0 and 5.1, and recent beta versions of
187 Debian.  Those distributions include the version of LinuxThreads matching
188 glibc 2.<P>
189
190 <H4><A NAME="C.2">C.2: My system has libc 5 preinstalled, not glibc
191 2.  Can I still use LinuxThreads?</H4>
192
193 Yes, but you're likely to run into some problems, as libc 5 only
194 offers minimal support for threads and contains some bugs that affect
195 multithreaded programs. <P>
196
197 The versions of libc 5 that work best with LinuxThreads are
198 libc 5.2.18 on the one hand, and libc 5.4.12 or later on the other hand.
199 Avoid 5.3.12 and 5.4.7: these have problems with the per-thread errno
200 variable. <P>
201
202 Unfortunately, many popular Linux distributions (e.g. RedHat 4.2) come
203 with libc 5.3.12 preinstalled -- the one that does not work with
204 LinuxThreads.  Fortunately, you can often find pre-packaged binaries
205 of more recent versions of libc for these distributions.  In the case
206 of RedHat 4, there is a RPM package for libc-5.4 in the "contrib"
207 area of RedHat FTP sites.
208 <P>
209
210 <H4><A NAME="C.3">C.3: So, should I switch to glibc 2, or stay with a
211 recent libc 5?</A></H4>
212
213 I'd recommend you switch to glibc 2.  Even for single-threaded
214 programs, glibc 2 is more solid and more standard-conformant than libc
215 5.  And the shortcomings of libc 5 almost preclude any serious
216 multi-threaded programming.<P>
217
218 Switching an already installed
219 system from libc 5 to glibc 2 is not completely straightforward.
220 See the <A HREF="http://sunsite.unc.edu/LDP/HOWTO/Glibc2-HOWTO.html">Glibc2
221 HOWTO</A> for more information.  Much easier is (re-)installing a
222 Linux distribution based on glibc 2, such as RedHat 5.1.<P>
223
224 <H4><A NAME="C.4">C.4: Where can I find glibc 2 and the version of
225 LinuxThreads that goes with it?</A></H4>
226
227 On <code>prep.ai.mit.edu</code> and its many, many mirrors around the world.
228 See <A
229 HREF="http://www.gnu.org/order/ftp.html">http://www.gnu.org/order/ftp.html</A>
230 for a list of mirrors.<P>
231
232 <H4><A NAME="C.5">C.5: Where can I find libc 5 and the version of
233 LinuxThreads that goes with it?</A></H4>
234
235 For libc 5, see <A HREF="ftp://sunsite.unc.edu/pub/Linux/devel/GCC/"><code>ftp://sunsite.unc.edu/pub/Linux/devel/GCC/</code></A>.<P>
236
237 For the libc 5 version of LinuxThreads, see
238 <A HREF="ftp://ftp.inria.fr/INRIA/Projects/cristal/Xavier.Leroy/linuxthreads/">ftp://ftp.inria.fr/INRIA/Projects/cristal/Xavier.Leroy/linuxthreads/</A>.<P>
239
240 <HR>
241 <P>
242
243 <H2><A NAME="D">D. Problems, weird behaviors, potential bugs</A></H2>
244
245 <H4><A NAME="D.1">D.1: When I compile LinuxThreads, I run into problems in
246 file <code>libc_r/dirent.c</code></A></H4>
247
248 You probably mean:
249 <PRE>
250         libc_r/dirent.c:94: structure has no member named `dd_lock'
251 </PRE>
252 I haven't actually seen this problem, but several users reported it.
253 My understanding is that something is wrong in the include files of
254 your Linux installation (<code>/usr/include/*</code>). Make sure
255 you're using a supported version of the libc 5 library. (See question <A
256 HREF="#C.2">C.2</A>).<P>
257
258 <H4><A NAME="D.2">D.2: When I compile LinuxThreads, I run into problems with
259 <CODE>/usr/include/sched.h</CODE>: there are several occurrences of
260 <CODE>_p</CODE> that the C compiler does not understand</A></H4>
261
262 Yes, <CODE>/usr/include/sched.h</CODE> that comes with libc 5.3.12 is broken.
263 Replace it with the <code>sched.h</code> file contained in the
264 LinuxThreads distribution.  But really you should not be using libc
265 5.3.12 with LinuxThreads! (See question <A HREF="#C.2">C.1</A>.)<P>
266
267 <H4><A NAME="D.3">D.3: My program does <CODE>fdopen()</CODE> on a file
268 descriptor opened on a pipe.  When I link it with LinuxThreads,
269 <CODE>fdopen()</CODE> always returns NULL!</A></H4>
270
271 You're using one of the buggy versions of libc (5.3.12, 5.4.7., etc).
272 See question <A HREF="#C.1">C.1</A> above.<P>
273
274 <H4><A NAME="D.4">D.4: My program crashes the first time it calls
275 <CODE>pthread_create()</CODE> !</A></H4>
276
277 You wouldn't be using glibc 2.0, by any chance?  That's a known bug
278 with glibc 2.0.  Please upgrade to 2.0.1 or later.<P>
279
280 <H4><A NAME="D.5">D.5: When I'm running a program that creates N
281 threads, <code>top</code> or <code>ps</code>
282 display N+2 processes that are running my program. What do all these
283 processes correspond to?</A></H4>
284
285 Due to the general "one process per thread" model, there's one process
286 for the initial thread and N processes for the threads it created
287 using <CODE>pthread_create</CODE>.  That leaves one process
288 unaccounted for.  That extra process corresponds to the "thread
289 manager" thread, a thread created internally by LinuxThreads to handle
290 thread creation and thread termination.  This extra thread is asleep
291 most of the time.
292
293 <H4><A NAME="D.6">D.6: Scheduling seems to be very unfair when there
294 is strong contention on a mutex: instead of giving the mutex to each
295 thread in turn, it seems that it's almost always the same thread that
296 gets the mutex. Isn't this completely broken behavior?</A></H4>
297
298 That behavior has mostly disappeared in recent releases of
299 LinuxThreads (version 0.8 and up).  It was fairly common in older
300 releases, though.
301
302 What happens in LinuxThreads 0.7 and before is the following: when a
303 thread unlocks a mutex, all other threads that were waiting on the
304 mutex are sent a signal which makes them runnable.  However, the
305 kernel scheduler may or may not restart them immediately.  If the
306 thread that unlocked the mutex tries to lock it again immediately
307 afterwards, it is likely that it will succeed, because the threads
308 haven't yet restarted.  This results in an apparently very unfair
309 behavior, when the same thread repeatedly locks and unlocks the mutex,
310 while other threads can't lock the mutex.<P>
311
312 In LinuxThreads 0.8 and up, <code>pthread_unlock</code> restarts only
313 one waiting thread, and pre-assign the mutex to that thread.  Hence,
314 if the thread that unlocked the mutex tries to lock it again
315 immediately, it will block until other waiting threads have had a
316 chance to lock and unlock the mutex.  This results in much fairer
317 scheduling.<P>
318
319 Notice however that even the old "unfair" behavior is perfectly
320 acceptable with respect to the POSIX standard: for the default
321 scheduling policy, POSIX makes no guarantees of fairness, such as "the
322 thread waiting for the mutex for the longest time always acquires it
323 first".  Properly written multithreaded code avoids that kind of heavy
324 contention on mutexes, and does not run into fairness problems.  If
325 you need scheduling guarantees, you should consider using the
326 real-time scheduling policies <code>SCHED_RR</code> and
327 <code>SCHED_FIFO</code>, which have precisely defined scheduling
328 behaviors. <P>
329
330 <H4><A NAME="D.7">D.7: I have a simple test program with two threads
331 that do nothing but <CODE>printf()</CODE> in tight loops, and from the
332 printout it seems that only one thread is running, the other doesn't
333 print anything!</A></H4>
334
335 Again, this behavior is characteristic of old releases of LinuxThreads
336 (0.7 and before); more recent versions (0.8 and up) should not exhibit
337 this behavior.<P>
338
339 The reason for this behavior is explained in
340 question <A HREF="#D.6">D.6</A> above: <CODE>printf()</CODE> performs
341 locking on <CODE>stdout</CODE>, and thus your two threads contend very
342 heavily for the mutex associated with <CODE>stdout</CODE>.  But if you
343 do some real work between two calls to <CODE>printf()</CODE>, you'll
344 see that scheduling becomes much smoother.<P>
345
346 <H4><A NAME="D.8">D.8: I've looked at <code>&lt;pthread.h&gt;</code>
347 and there seems to be a gross error in the <code>pthread_cleanup_push</code>
348 macro: it opens a block with <code>{</code> but does not close it!
349 Surely you forgot a <code>}</code> at the end of the macro, right?
350 </A></H4>
351
352 Nope.  That's the way it should be.  The closing brace is provided by
353 the <code>pthread_cleanup_pop</code> macro.  The POSIX standard
354 requires <code>pthread_cleanup_push</code> and
355 <code>pthread_cleanup_pop</code> to be used in matching pairs, at the
356 same level of brace nesting.  This allows
357 <code>pthread_cleanup_push</code> to open a block in order to
358 stack-allocate some data structure, and
359 <code>pthread_cleanup_pop</code> to close that block.  It's ugly, but
360 it's the standard way of implementing cleanup handlers.<P>
361
362 <HR>
363 <P>
364
365 <H2><A NAME="E">E. Missing functions, wrong types, etc</A></H2>
366
367 <H4><A NAME="E.1">E.1: Where is <CODE>pthread_yield()</CODE> ? How
368 comes LinuxThreads does not implement it?</A></H4>
369
370 Because it's not part of the (final) POSIX 1003.1c standard.
371 Several drafts of the standard contained <CODE>pthread_yield()</CODE>,
372 but then the POSIX guys discovered it was redundant with
373 <CODE>sched_yield()</CODE> and dropped it.  So, just use
374 <CODE>sched_yield()</CODE> instead.
375
376 <H4><A NAME="E.2">E.2: I've found some type errors in
377 <code>&lt;pthread.h&gt;</code>.
378 For instance, the second argument to <CODE>pthread_create()</CODE>
379 should be a <CODE>pthread_attr_t</CODE>, not a
380 <CODE>pthread_attr_t *</CODE>. Also, didn't you forget to declare
381 <CODE>pthread_attr_default</CODE>?</A></H4>
382
383 No, I didn't.  What you're describing is draft 4 of the POSIX
384 standard, which is used in OSF DCE threads.  LinuxThreads conforms to the
385 final standard.  Even though the functions have the same names as in
386 draft 4 and DCE, their calling conventions are slightly different.  In
387 particular, attributes are passed by reference, not by value, and
388 default attributes are denoted by the NULL pointer.  Since draft 4/DCE
389 will eventually disappear, you'd better port your program to use the
390 standard interface.<P>
391
392 <H4><A NAME="E.3">E.3: I'm porting an application from Solaris and I
393 have to rename all thread functions from <code>thr_blah</code> to
394 <CODE>pthread_blah</CODE>.  This is very annoying.  Why did you change
395 all the function names?</A></H4>
396
397 POSIX did it.  The <code>thr_*</code> functions correspond to Solaris
398 threads, an older thread interface that you'll find only under
399 Solaris.  The <CODE>pthread_*</CODE> functions correspond to POSIX
400 threads, an international standard available for many, many platforms.
401 Even Solaris 2.5 and later support the POSIX threads interface.  So,
402 do yourself a favor and rewrite your code to use POSIX threads: this
403 way, it will run unchanged under Linux, Solaris, and quite a lot of
404 other platforms.<P>
405
406 <H4><A NAME="E.4">E.4: How can I suspend and resume a thread from
407 another thread? Solaris has the <CODE>thr_suspend()</CODE> and
408 <CODE>thr_resume()</CODE> functions to do that; why don't you?</A></H4>
409
410 The POSIX standard provides <B>no</B> mechanism by which a thread A can
411 suspend the execution of another thread B, without cooperation from B.
412 The only way to implement a suspend/restart mechanism is to have B
413 check periodically some global variable for a suspend request
414 and then suspend itself on a condition variable, which another thread
415 can signal later to restart B.<P>
416
417 Notice that <CODE>thr_suspend()</CODE> is inherently dangerous and
418 prone to race conditions.  For one thing, there is no control on where
419 the target thread stops: it can very well be stopped in the middle of
420 a critical section, while holding mutexes.  Also, there is no
421 guarantee on when the target thread will actually stop.  For these
422 reasons, you'd be much better off using mutexes and conditions
423 instead.  The only situations that really require the ability to
424 suspend a thread are debuggers and some kind of garbage collectors.<P>
425
426 If you really must suspend a thread in LinuxThreads, you can send it a
427 <CODE>SIGSTOP</CODE> signal with <CODE>pthread_kill</CODE>. Send
428 <CODE>SIGCONT</CODE> for restarting it.
429 Beware, this is specific to LinuxThreads and entirely non-portable.
430 Indeed, a truly conforming POSIX threads implementation will stop all
431 threads when one thread receives the <CODE>SIGSTOP</CODE> signal!
432 One day, LinuxThreads will implement that behavior, and the
433 non-portable hack with <CODE>SIGSTOP</CODE> won't work anymore.<P>
434
435 <H4><A NAME="E.5">E.5: Does LinuxThreads implement
436 <CODE>pthread_attr_setstacksize()</CODE> and
437 <CODE>pthread_attr_setstackaddr()</CODE>?</A></H4>
438
439 These optional functions are provided in recent versions of
440 LinuxThreads (0.8 and up).  Earlier releases did not provide these
441 optional components of the POSIX standard.<P>
442
443 Even if <CODE>pthread_attr_setstacksize()</CODE> and
444 <CODE>pthread_attr_setstackaddr()</CODE> are now provided, we still
445 recommend that you do not use them unless you really have strong
446 reasons for doing so.  The default stack allocation strategy for
447 LinuxThreads is nearly optimal: stacks start small (4k) and
448 automatically grow on demand to a fairly large limit (2M).
449 Moreover, there is no portable way to estimate the stack requirements
450 of a thread, so setting the stack size yourself makes your program
451 less reliable and non-portable.<P>
452
453 <H4><A NAME="E.6">E.6: LinuxThreads does not support the
454 <CODE>PTHREAD_SCOPE_PROCESS</CODE> value of the "contentionscope"
455 attribute.  Why? </A></H4>
456
457 With a "one-to-one" model, as in LinuxThreads (one kernel execution
458 context per thread), there is only one scheduler for all processes and
459 all threads on the system.  So, there is no way to obtain the behavior of
460 <CODE>PTHREAD_SCOPE_PROCESS</CODE>.
461
462 <H4><A NAME="E.7">E.7: LinuxThreads does not implement process-shared
463 mutexes, conditions, and semaphores. Why?</A></H4>
464
465 This is another optional component of the POSIX standard.  Portable
466 applications should test <CODE>_POSIX_THREAD_PROCESS_SHARED</CODE>
467 before using this facility.
468 <P>
469 The goal of this extension is to allow different processes (with
470 different address spaces) to synchronize through mutexes, conditions
471 or semaphores allocated in shared memory (either SVR4 shared memory
472 segments or <CODE>mmap()</CODE>ed files).
473 <P>
474 The reason why this does not work in LinuxThreads is that mutexes,
475 conditions, and semaphores are not self-contained: their waiting
476 queues contain pointers to linked lists of thread descriptors, and
477 these pointers are meaningful only in one address space.
478 <P>
479 Matt Messier and I spent a significant amount of time trying to design a
480 suitable mechanism for sharing waiting queues between processes.  We
481 came up with several solutions that combined two of the following
482 three desirable features, but none that combines all three:
483 <UL>
484 <LI>allow sharing between processes having different UIDs
485 <LI>supports cancellation
486 <LI>supports <CODE>pthread_cond_timedwait</CODE>
487 </UL>
488 We concluded that kernel support is required to share mutexes,
489 conditions and semaphores between processes.  That's one place where
490 Linus Torvalds's intuition that "all we need in the kernel is
491 <CODE>clone()</CODE>" fails.
492 <P>
493 Until suitable kernel support is available, you'd better use
494 traditional interprocess communications to synchronize different
495 processes: System V semaphores and message queues, or pipes, or sockets.
496 <P>
497
498 <HR>
499 <P>
500
501 <H2><A NAME="F">F. C++ issues</A></H2>
502
503 <H4><A NAME="F.1">F.1: Are there C++ wrappers for LinuxThreads?</A></H4>
504
505 Douglas Schmidt's ACE library contains, among a lot of other
506 things, C++ wrappers for LinuxThreads and quite a number of other
507 thread libraries.  Check out
508 <A HREF="http://www.cs.wustl.edu/~schmidt/ACE.html">http://www.cs.wustl.edu/~schmidt/ACE.html</A><P>
509
510 <H4><A NAME="F.2">F.2: I'm trying to use LinuxThreads from a C++
511 program, and the compiler complains about the third argument to
512 <CODE>pthread_create()</CODE> !</A></H4>
513
514 You're probably trying to pass a class member function or some
515 other C++ thing as third argument to <CODE>pthread_create()</CODE>.
516 Recall that <CODE>pthread_create()</CODE> is a C function, and it must
517 be passed a C function as third argument.<P>
518
519 <H4><A NAME="F.3">F.3: I'm trying to use LinuxThreads in conjunction
520 with libg++, and I'm having all sorts of trouble.</A></H4>
521
522 From what I understand, thread support in libg++ is completely broken,
523 especially with respect to locking of iostreams.  H.J.Lu wrote:
524 <BLOCKQUOTE>
525 If you want to use thread, I can only suggest egcs and glibc. You
526 can find egcs at
527 <A HREF="http://www.cygnus.com/egcs">http://www.cygnus.com/egcs</A>.
528 egcs has libsdtc++, which is MT safe under glibc 2. If you really
529 want to use the libg++, I have a libg++ add-on for egcs.
530 </BLOCKQUOTE>
531 <HR>
532 <P>
533
534 <H2><A NAME="G">G. Debugging LinuxThreads programs</A></H2>
535
536 <H4><A NAME="G.1">G.1: Can I debug LinuxThreads program using gdb?</A></H4>
537
538 Yes, but not with the stock gdb 4.17.  You need a specially patched
539 version of gdb 4.17 developed by Eric Paire and colleages at The Open
540 Group, Grenoble.  The patches against gdb 4.17 are available at
541 <A HREF="http://www.gr.opengroup.org/java/jdk/linux/debug.htm"><code>http://www.gr.opengroup.org/java/jdk/linux/debug.htm</code></A>.
542 Precompiled binaries of the patched gdb are available in RedHat's RPM
543 format at <A HREF="http://odin.appliedtheory.com/"><code>http://odin.appliedtheory.com/</code></A>.
544
545 <H4><A NAME="G.2">G.2: Does it work with post-mortem debugging?</A></H4>
546
547 Not very well.  Generally, the core file does not correspond to the
548 thread that crashed.  The reason is that the kernel will not dump core
549 for a process that shares its memory with other processes, such as the
550 other threads of your program.  So, the thread that crashes silently
551 disappears without generating a core file.  Then, all other threads of
552 your program die on the same signal that killed the crashing thread.
553 (This is required behavior according to the POSIX standard.)  The last
554 one that dies is no longer sharing its memory with anyone else, so the
555 kernel generates a core file for that thread.  Unfortunately, that's
556 not the thread you are interested in.
557
558 <H4><A NAME="G.3">G.3: Any other ways to debug multithreaded programs, then?</A></H4>
559
560 Assertions and <CODE>printf()</CODE> are your best friends.  Try to debug
561 sequential parts in a single-threaded program first.  Then, put
562 <CODE>printf()</CODE> statements all over the place to get execution traces.
563 Also, check invariants often with the <CODE>assert()</CODE> macro.  In truth,
564 there is no other effective way (save for a full formal proof of your
565 program) to track down concurrency bugs.  Debuggers are not really
566 effective for subtle concurrency problems, because they disrupt
567 program execution too much.<P>
568
569 <HR>
570 <P>
571
572 <H2><A NAME="H">H. Compiling multithreaded code; errno madness</A></H2>
573
574 <H4><A NAME="H.1">H.1: You say all multithreaded code must be compiled
575 with <CODE>_REENTRANT</CODE> defined. What difference does it make?</A></H4>
576
577 It affects include files in three ways:
578 <UL>
579 <LI> The include files define prototypes for the reentrant variants of
580 some of the standard library functions,
581 e.g. <CODE>gethostbyname_r()</CODE> as a reentrant equivalent to
582 <CODE>gethostbyname()</CODE>.<P>
583
584 <LI> If <CODE>_REENTRANT</CODE> is defined, some
585 <code>&lt;stdio.h&gt;</code> functions are no longer defined as macros,
586 e.g. <CODE>getc()</CODE> and <CODE>putc()</CODE>. In a multithreaded
587 program, stdio functions require additional locking, which the macros
588 don't perform, so we must call functions instead.<P>
589
590 <LI> More importantly, <code>&lt;errno.h&gt;</code> redefines errno when
591 <CODE>_REENTRANT</CODE> is
592 defined, so that errno refers to the thread-specific errno location
593 rather than the global errno variable.  This is achieved by the
594 following <code>#define</code> in <code>&lt;errno.h&gt;</code>:
595 <PRE>
596         #define errno (*(__errno_location()))
597 </PRE>
598 which causes each reference to errno to call the
599 <CODE>__errno_location()</CODE> function for obtaining the location
600 where error codes are stored.  libc provides a default definition of
601 <CODE>__errno_location()</CODE> that always returns
602 <code>&errno</code> (the address of the global errno variable). Thus,
603 for programs not linked with LinuxThreads, defining
604 <CODE>_REENTRANT</CODE> makes no difference w.r.t. errno processing.
605 But LinuxThreads redefines <CODE>__errno_location()</CODE> to return a
606 location in the thread descriptor reserved for holding the current
607 value of errno for the calling thread.  Thus, each thread operates on
608 a different errno location.
609 </UL>
610 <P>
611
612 <H4><A NAME="H.2">H.2: Why is it so important that each thread has its
613 own errno variable? </A></H4>
614
615 If all threads were to store error codes in the same, global errno
616 variable, then the value of errno after a system call or library
617 function returns would be unpredictable:  between the time a system
618 call stores its error code in the global errno and your code inspects
619 errno to see which error occurred, another thread might have stored
620 another error code in the same errno location. <P>
621
622 <H4><A NAME="H.3">H.3: What happens if I link LinuxThreads with code
623 not compiled with <CODE>-D_REENTRANT</CODE>?</A></H4>
624
625 Lots of trouble.  If the code uses <CODE>getc()</CODE> or
626 <CODE>putc()</CODE>, it will perform I/O without proper interlocking
627 of the stdio buffers; this can cause lost output, duplicate output, or
628 just crash other stdio functions.  If the code consults errno, it will
629 get back the wrong error code.  The following code fragment is a
630 typical example:
631 <PRE>
632         do {
633           r = read(fd, buf, n);
634           if (r == -1) {
635             if (errno == EINTR)   /* an error we can handle */
636               continue;
637             else {                /* other errors are fatal */
638               perror("read failed");
639               exit(100);
640             }
641           }
642         } while (...);
643 </PRE>
644 Assume this code is not compiled with <CODE>-D_REENTRANT</CODE>, and
645 linked with LinuxThreads.  At run-time, <CODE>read()</CODE> is
646 interrupted.  Since the C library was compiled with
647 <CODE>-D_REENTRANT</CODE>, <CODE>read()</CODE> stores its error code
648 in the location pointed to by <CODE>__errno_location()</CODE>, which
649 is the thread-local errno variable.  Then, the code above sees that
650 <CODE>read()</CODE> returns -1 and looks up errno.  Since
651 <CODE>_REENTRANT</CODE> is not defined, the reference to errno
652 accesses the global errno variable, which is most likely 0.  Hence the
653 code concludes that it cannot handle the error and stops.<P>
654
655 <H4><A NAME="H.4">H.4: With LinuxThreads, I can no longer use the signals
656 <code>SIGUSR1</code> and <code>SIGUSR2</code> in my programs! Why? </A></H4>
657
658 The short answer is: because the Linux kernel you're using does not
659 support realtime signals.  <P>
660
661 LinuxThreads needs two signals for its internal operation.
662 One is used to suspend and restart threads blocked on mutex, condition
663 or semaphore operations.  The other is used for thread
664 cancellation.<P>
665
666 On ``old'' kernels (2.0 and early 2.1 kernels), there are only 32
667 signals available and the kernel reserves all of them but two:
668 <code>SIGUSR1</code> and <code>SIGUSR2</code>.  So, LinuxThreads has
669 no choice but use those two signals.<P>
670
671 On recent kernels (late 2.1 kernels and the forthcoming 2.2 kernels),
672 more than 32 signals are provided in the form of realtime signals.
673 When run on one of those kernels, LinuxThreads uses two reserved
674 realtime signals for its internal operation, thus leaving
675 <code>SIGUSR1</code> and <code>SIGUSR2</code> free for user code.<P>
676
677 <H4><A NAME="H.5">H.5: Is the stack of one thread visible from the
678 other threads?  Can I pass a pointer into my stack to other threads?
679 </A></H4>
680
681 Yes, you can -- if you're very careful.  The stacks are indeed visible
682 from all threads in the system.  Some non-POSIX thread libraries seem
683 to map the stacks for all threads at the same virtual addresses and
684 change the memory mapping when they switch from one thread to
685 another.  But this is not the case for LinuxThreads, as it would make
686 context switching between threads more expensive, and at any rate
687 might not conform to the POSIX standard.<P>
688
689 So, you can take the address of an "auto" variable and pass it to
690 other threads via shared data structures.  However, you need to make
691 absolutely sure that the function doing this will not return as long
692 as other threads need to access this address.  It's the usual mistake
693 of returning the address of an "auto" variable, only made much worse
694 because of concurrency.  It's much, much safer to systematically
695 heap-allocate all shared data structures. <P>
696
697 <HR>
698 <P>
699
700 <H2><A NAME="I">I.  X-Windows and other libraries</A></H2>
701
702 <H4><A NAME="I.1">I.1: My program uses both Xlib and LinuxThreads.
703 It stops very early with an "Xlib: unknown 0 error" message.  What
704 does this mean? </A></H4>
705
706 That's a prime example of the errno problem described in question <A
707 HREF="#H.2">H.2</A>.  The binaries for Xlib you're using have not been
708 compiled with <CODE>-D_REENTRANT</CODE>.  It happens Xlib contains a
709 piece of code very much like the one in question <A
710 HREF="#H.2">H.2</A>.  So, your Xlib fetches the error code from the
711 wrong errno location and concludes that an error it cannot handle
712 occurred.<P>
713
714 <H4><A NAME="I.2">I.2: So, what can I do to build a multithreaded X
715 Windows client? </A></H4>
716
717 The best solution is to use X libraries that have been compiled with
718 multithreading options set.  Linux distributions that come with glibc
719 2 as the main C library generally provide thread-safe X libraries.
720 At least, that seems to be the case for RedHat 5.<P>
721
722 You can try to recompile yourself the X libraries with multithreading
723 options set.  They contain optional support for multithreading; it's
724 just that the binaries provided by your Linux distribution were built
725 without this support.  See the file <code>README.Xfree3.3</code> in
726 the LinuxThreads distribution for patches and info on how to compile
727 thread-safe X libraries from the Xfree3.3 distribution.  The Xfree3.3
728 sources are readily available in most Linux distributions, e.g. as a
729 source RPM for RedHat.  Be warned, however, that X Windows is a huge
730 system, and recompiling even just the libraries takes a lot of time
731 and disk space.<P>
732
733 Another, less involving solution is to call X functions only from the
734 main thread of your program.  Even if all threads have their own errno
735 location, the main thread uses the global errno variable for its errno
736 location.  Thus, code not compiled with <code>-D_REENTRANT</code>
737 still "sees" the right error values if it executes in the main thread
738 only. <P>
739
740 <H4><A NAME="I.2">This is a lot of work. Don't you have precompiled
741 thread-safe X libraries that you could distribute?</A></H4>
742
743 No, I don't.  Sorry.  But consider installing a Linux distribution
744 that comes with thread-safe X libraries, such as RedHat 5.<P>
745
746 <H4><A NAME="I.3">I.3: Can I use library FOO in a multithreaded
747 program?</A></H4>
748
749 Most libraries cannot be used "as is" in a multithreaded program.
750 For one thing, they are not necessarily thread-safe: calling
751 simultaneously two functions of the library from two threads might not
752 work, due to internal use of global variables and the like.  Second,
753 the libraries must have been compiled with <CODE>-D_REENTRANT</CODE> to avoid
754 the errno problems explained in question <A HREF="#H.2">H.2</A>.
755 <P>
756
757 <H4><A NAME="I.4">I.4: What if I make sure that only one thread calls
758 functions in these libraries?</A></H4>
759
760 This avoids problems with the library not being thread-safe.  But
761 you're still vulnerable to errno problems.  At the very least, a
762 recompile of the library with <CODE>-D_REENTRANT</CODE> is needed.
763 <P>
764
765 <H4><A NAME="I.5">I.5: What if I make sure that only the main thread
766 calls functions in these libraries?</A></H4>
767
768 That might actually work.  As explained in question <A HREF="#I.1">I.1</A>,
769 the main thread uses the global errno variable, and can therefore
770 execute code not compiled with <CODE>-D_REENTRANT</CODE>.<P>
771
772 <H4><A NAME="I.6">I.6: SVGAlib doesn't work with LinuxThreads.  Why?
773 </A></H4>
774
775 Because both LinuxThreads and SVGAlib use the signals
776 <code>SIGUSR1</code> and <code>SIGUSR2</code>.  See question <A
777 HREF="#H.4">H.4</A>.
778 <P>
779
780
781 <HR>
782 <P>
783
784 <H2><A NAME="J">J.  Signals and threads</A></H2>
785
786 <H4><A NAME="J.1">J.1: When it comes to signals, what is shared
787 between threads and what isn't?</A></H4>
788
789 Signal handlers are shared between all threads: when a thread calls
790 <CODE>sigaction()</CODE>, it sets how the signal is handled not only
791 for itself, but for all other threads in the program as well.<P>
792
793 On the other hand, signal masks are per-thread: each thread chooses
794 which signals it blocks independently of others.  At thread creation
795 time, the newly created thread inherits the signal mask of the thread
796 calling <CODE>pthread_create()</CODE>.  But afterwards, the new thread
797 can modify its signal mask independently of its creator thread.<P>
798
799 <H4><A NAME="J.2">J.2: When I send a <CODE>SIGKILL</CODE> to a
800 particular thread using <CODE>pthread_kill</CODE>, all my threads are
801 killed!</A></H4>
802
803 That's how it should be.  The POSIX standard mandates that all threads
804 should terminate when the process (i.e. the collection of all threads
805 running the program) receives a signal whose effect is to
806 terminate the process (such as <CODE>SIGKILL</CODE> or <CODE>SIGINT</CODE>
807 when no handler is installed on that signal).  This behavior makes a
808 lot of sense: when you type "ctrl-C" at the keyboard, or when a thread
809 crashes on a division by zero or a segmentation fault, you really want
810 all threads to stop immediately, not just the one that caused the
811 segmentation violation or that got the <CODE>SIGINT</CODE> signal.
812 (This assumes default behavior for those signals; see question
813 <A HREF="#J.3">J.3</A> if you install handlers for those signals.)<P>
814
815 If you're trying to terminate a thread without bringing the whole
816 process down, use <code>pthread_cancel()</code>.<P>
817
818 <H4><A NAME="J.3">J.3: I've installed a handler on a signal.  Which
819 thread executes the handler when the signal is received?</A></H4>
820
821 If the signal is generated by a thread during its execution (e.g. a
822 thread executes a division by zero and thus generates a
823 <CODE>SIGFPE</CODE> signal), then the handler is executed by that
824 thread.  This also applies to signals generated by
825 <CODE>raise()</CODE>.<P>
826
827 If the signal is sent to a particular thread using
828 <CODE>pthread_kill()</CODE>, then that thread executes the handler.<P>
829
830 If the signal is sent via <CODE>kill()</CODE> or the tty interface
831 (e.g. by pressing ctrl-C), then the POSIX specs say that the handler
832 is executed by any thread in the process that does not currently block
833 the signal.  In other terms, POSIX considers that the signal is sent
834 to the process (the collection of all threads) as a whole, and any
835 thread that is not blocking this signal can then handle it.<P>
836
837 The latter case is where LinuxThreads departs from the POSIX specs.
838 In LinuxThreads, there is no real notion of ``the process as a whole'':
839 in the kernel, each thread is really a distinct process with a
840 distinct PID, and signals sent to the PID of a thread can only be
841 handled by that thread.  As long as no thread is blocking the signal,
842 the behavior conforms to the standard: one (unspecified) thread of the
843 program handles the signal.  But if the thread to which PID the signal
844 is sent blocks the signal, and some other thread does not block the
845 signal, then LinuxThreads will simply queue in
846 that thread and execute the handler only when that thread unblocks
847 the signal, instead of executing the handler immediately in the other
848 thread that does not block the signal.<P>
849
850 This is to be viewed as a LinuxThreads bug, but I currently don't see
851 any way to implement the POSIX behavior without kernel support.<P>
852
853 <H4><A NAME="J.3">J.3: How shall I go about mixing signals and threads
854 in my program? </A></H4>
855
856 The less you mix them, the better.  Notice that all
857 <CODE>pthread_*</CODE> functions are not async-signal safe, meaning
858 that you should not call them from signal handlers.  This
859 recommendation is not to be taken lightly: your program can deadlock
860 if you call a <CODE>pthread_*</CODE> function from a signal handler!
861 <P>
862
863 The only sensible things you can do from a signal handler is set a
864 global flag, or call <CODE>sem_post</CODE> on a semaphore, to record
865 the delivery of the signal.  The remainder of the program can then
866 either poll the global flag, or use <CODE>sem_wait()</CODE> and
867 <CODE>sem_trywait()</CODE> on the semaphore.<P>
868
869 Another option is to do nothing in the signal handler, and dedicate
870 one thread (preferably the initial thread) to wait synchronously for
871 signals, using <CODE>sigwait()</CODE>, and send messages to the other
872 threads accordingly.
873
874 <H4><A NAME="J.4">J.4: When one thread is blocked in
875 <CODE>sigwait()</CODE>, other threads no longer receive the signals
876 <CODE>sigwait()</CODE> is waiting for!  What happens? </A></H4>
877
878 It's an unfortunate consequence of how LinuxThreads implements
879 <CODE>sigwait()</CODE>.  Basically, it installs signal handlers on all
880 signals waited for, in order to record which signal was received.
881 Since signal handlers are shared with the other threads, this
882 temporarily deactivates any signal handlers you might have previously
883 installed on these signals.<P>
884
885 Though surprising, this behavior actually seems to conform to the
886 POSIX standard.  According to POSIX, <CODE>sigwait()</CODE> is
887 guaranteed to work as expected only if all other threads in the
888 program block the signals waited for (otherwise, the signals could be
889 delivered to other threads than the one doing <CODE>sigwait()</CODE>,
890 which would make <CODE>sigwait()</CODE> useless).  In this particular
891 case, the problem described in this question does not appear.<P>
892
893 One day, <CODE>sigwait()</CODE> will be implemented in the kernel,
894 along with others POSIX 1003.1b extensions, and <CODE>sigwait()</CODE>
895 will have a more natural behavior (as well as better performances).<P>
896
897 <HR>
898 <P>
899
900 <H2><A NAME="K">K.  Internals of LinuxThreads</A></H2>
901
902 <H4><A NAME="K.1">K.1: What is the implementation model for
903 LinuxThreads?</A></H4>
904
905 LinuxThreads follows the so-called "one-to-one" model: each thread is
906 actually a separate process in the kernel.  The kernel scheduler takes
907 care of scheduling the threads, just like it schedules regular
908 processes.  The threads are created with the Linux
909 <code>clone()</code> system call, which is a generalization of
910 <code>fork()</code> allowing the new process to share the memory
911 space, file descriptors, and signal handlers of the parent.<P>
912
913 Advantages of the "one-to-one" model include:
914 <UL>
915 <LI> minimal overhead on CPU-intensive multiprocessing (with
916 about one thread per processor);
917 <LI> minimal overhead on I/O operations;
918 <LI> a simple and robust implementation (the kernel scheduler does
919 most of the hard work for us).
920 </UL>
921 The main disadvantage is more expensive context switches on mutex and
922 condition operations, which must go through the kernel.  This is
923 mitigated by the fact that context switches in the Linux kernel are
924 pretty efficient.<P>
925
926 <H4><A NAME="K.2">K.2: Have you considered other implementation
927 models?</A></H4>
928
929 There are basically two other models.  The "many-to-one" model
930 relies on a user-level scheduler that context-switches between the
931 threads entirely in user code; viewed from the kernel, there is only
932 one process running.  This model is completely out of the question for
933 me, since it does not take advantage of multiprocessors, and require
934 unholy magic to handle blocking I/O operations properly.  There are
935 several user-level thread libraries available for Linux, but I found
936 all of them deficient in functionality, performance, and/or robustness.
937 <P>
938
939 The "many-to-many" model combines both kernel-level and user-level
940 scheduling: several kernel-level threads run concurrently, each
941 executing a user-level scheduler that selects between user threads.
942 Most commercial Unix systems (Solaris, Digital Unix, IRIX) implement
943 POSIX threads this way.  This model combines the advantages of both
944 the "many-to-one" and the "one-to-one" model, and is attractive
945 because it avoids the worst-case behaviors of both models --
946 especially on kernels where context switches are expensive, such as
947 Digital Unix.  Unfortunately, it is pretty complex to implement, and
948 requires kernel support which Linux does not provide.  Linus Torvalds
949 and other Linux kernel developers have always been pushing the
950 "one-to-one" model in the name of overall simplicity, and are doing a
951 pretty good job of making kernel-level context switches between
952 threads efficient.  LinuxThreads is just following the general
953 direction they set.<P>
954
955 <HR>
956 <ADDRESS>Xavier.Leroy@inria.fr</ADDRESS>
957 </BODY>
958 </HTML>