]>
Commit | Line | Data |
---|---|---|
5afdca00 UD |
1 | Linuxthreads - POSIX 1003.1c kernel threads for Linux |
2 | ||
3 | Copyright 1996, 1997 Xavier Leroy (Xavier.Leroy@inria.fr) | |
4 | ||
5 | ||
6 | DESCRIPTION: | |
7 | ||
8 | This is release 0.7 (late beta) of LinuxThreads, a BiCapitalized | |
9 | implementation of the Posix 1003.1c "pthread" interface for Linux. | |
10 | ||
11 | LinuxThreads provides kernel-level threads: each thread is a separate | |
12 | Unix process, sharing its address space with the other threads through | |
13 | the new system call clone(). Scheduling between threads is handled by | |
14 | the kernel scheduler, just like scheduling between Unix processes. | |
15 | ||
16 | ||
17 | REQUIREMENTS: | |
18 | ||
19 | - Linux version 2.0 and up (requires the new clone() system call | |
20 | and the new realtime scheduler). | |
21 | ||
22 | - For Intel platforms: libc 5.2.18 or later is required. | |
23 | 5.2.18 or 5.4.12 or later are recommended; | |
24 | 5.3.12 and 5.4.7 have problems (see the FAQ.html file for more info). | |
25 | ||
26 | - Also supports glibc 2 (a.k.a. libc 6), which actually comes with | |
27 | a specially-adapted version of this library. | |
28 | ||
29 | - Currently supports Intel, Alpha, Sparc, Motorola 68k, ARM and MIPS | |
30 | platforms. | |
31 | ||
32 | - Multiprocessors are supported. | |
33 | ||
34 | ||
35 | INSTALLATION: | |
36 | ||
37 | - Edit the Makefile, set the variables in the "Configuration" section. | |
38 | ||
39 | - Do "make". | |
40 | ||
41 | - Do "make install". | |
42 | ||
43 | ||
44 | USING LINUXTHREADS: | |
45 | ||
46 | gcc -D_REENTRANT ... -lpthread | |
47 | ||
48 | A complete set of manual pages is included. Also see the subdirectory | |
49 | Examples/ for some sample programs. | |
50 | ||
51 | ||
52 | STATUS: | |
53 | ||
54 | - All functions in the Posix 1003.1c base interface implemented. | |
55 | Also supports priority scheduling. | |
56 | ||
57 | - For users of libc 5 (H.J.Lu's libc), a number of C library functions | |
58 | are reimplemented or wrapped to make them thread-safe, including: | |
59 | * malloc functions | |
60 | * stdio functions (define _REENTRANT before including <stdio.h>) | |
61 | * per-thread errno variable (define _REENTRANT before including <errno.h>) | |
62 | * directory reading functions (opendir(), etc) | |
63 | * sleep() | |
64 | * gmtime(), localtime() | |
65 | ||
66 | New library functions provided: | |
67 | * flockfile(), funlockfile(), ftrylockfile() | |
68 | * reentrant versions of network database functions (gethostbyname_r(), etc) | |
69 | and password functions (getpwnam_r(), etc). | |
70 | ||
71 | - libc 6 (glibc 2) provides much better thread support than libc 5, | |
72 | and comes with a specially-adapted version of LinuxThreads. | |
73 | For serious multithreaded programming, you should consider switching | |
5d409851 | 74 | to glibc 2. It is available from ftp.gnu.org:/pub/gnu and its mirrors. |
5afdca00 UD |
75 | |
76 | ||
77 | WARNING: | |
78 | ||
79 | Many existing libraries are not compatible with LinuxThreads, | |
80 | either because they are not inherently thread-safe, or because they | |
81 | have not been compiled with the -D_REENTRANT. For more info, see the | |
82 | FAQ.html file in this directory. | |
83 | ||
84 | A prime example of the latter is Xlib. If you link it with | |
85 | LinuxThreads, you'll probably get an "unknown 0 error" very | |
86 | early. This is just a consequence of the Xlib binaries using the | |
87 | global variable "errno" to fetch error codes, while LinuxThreads and | |
88 | the C library use the per-thread "errno" location. | |
89 | ||
90 | See the file README.Xfree3.3 for info on how to compile the Xfree 3.3 | |
91 | libraries to make them compatible with LinuxThreads. | |
92 | ||
93 | ||
94 | KNOWN BUGS AND LIMITATIONS: | |
95 | ||
96 | - Threads share pretty much everything they should share according | |
97 | to the standard: memory space, file descriptors, signal handlers, | |
98 | current working directory, etc. One thing that they do not share | |
99 | is their pid's and parent pid's. According to the standard, they | |
100 | should have the same, but that's one thing we cannot achieve | |
101 | in this implementation (until the CLONE_PID flag to clone() becomes | |
102 | usable). | |
103 | ||
104 | - The current implementation uses the two signals SIGUSR1 and SIGUSR2, | |
105 | so user-level code cannot employ them. Ideally, there should be two | |
106 | signals reserved for this library. One signal is used for restarting | |
107 | threads blocked on mutexes or conditions; the other is for thread | |
108 | cancellation. | |
109 | ||
5d409851 UD |
110 | *** This is not anymore true when the application runs on a kernel |
111 | newer than approximately 2.1.60. | |
112 | ||
5afdca00 UD |
113 | - The stacks for the threads are allocated high in the memory space, |
114 | below the stack of the initial process, and spaced 2M apart. | |
115 | Stacks are allocated with the "grow on demand" flag, so they don't | |
116 | use much virtual space initially (4k, currently), but can grow | |
117 | up to 2M if needed. | |
118 | ||
119 | Reserving such a large address space for each thread means that, | |
120 | on a 32-bit architecture, no more than about 1000 threads can | |
121 | coexist (assuming a 2Gb address space for user processes), | |
122 | but this is reasonable, since each thread uses up one entry in the | |
123 | kernel's process table, which is usually limited to 512 processes. | |
124 | ||
125 | Another potential problem of the "grow on demand" scheme is that | |
126 | nothing prevents the user from mmap'ing something in the 2M address | |
127 | window reserved for a thread stack, possibly causing later extensions of | |
128 | that stack to fail. Mapping at fixed addresses should be avoided | |
129 | when using this library. | |
130 | ||
131 | - Signal handling does not fully conform to the Posix standard, | |
132 | due to the fact that threads are here distinct processes that can be | |
133 | sent signals individually, so there's no notion of sending a signal | |
134 | to "the" process (the collection of all threads). | |
135 | More precisely, here is a summary of the standard requirements | |
136 | and how they are met by the implementation: | |
137 | ||
138 | 1- Synchronous signals (generated by the thread execution, e.g. SIGFPE) | |
139 | are delivered to the thread that raised them. | |
140 | (OK.) | |
141 | ||
142 | 2- A fatal asynchronous signal terminates all threads in the process. | |
143 | (OK. The thread manager notices when a thread dies on a signal | |
144 | and kills all other threads with the same signal.) | |
145 | ||
146 | 3- An asynchronous signal will be delivered to one of the threads | |
147 | of the program which does not block the signal (it is unspecified | |
148 | which). | |
149 | (No, the signal is delivered to the thread it's been sent to, | |
150 | based on the pid of the thread. If that thread is currently | |
151 | blocking the signal, the signal remains pending.) | |
152 | ||
153 | 4- The signal will be delivered to at most one thread. | |
154 | (OK, except for signals generated from the terminal or sent to | |
155 | the process group, which will be delivered to all threads.) | |
156 | ||
157 | - The current implementation of the MIPS support assumes a MIPS ISA II | |
158 | processor or better. These processors support atomic operations by | |
159 | ll/sc instructions. Older R2000/R3000 series processors are not | |
160 | supported yet; support for these will have higher overhead. | |
161 | ||
162 | - The current implementation of the ARM support assumes that the SWP | |
163 | (atomic swap register with memory) instruction is available. This is | |
164 | the case for all processors except for the ARM1 and ARM2. On StrongARM, | |
165 | the SWP instruction does not bypass the cache, so multi-processor support | |
166 | will be more troublesome. |