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