linuxthreads/README

   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
  74   to glibc 2. It is available from ftp.gnu.org:/pub/gnu and its mirrors.
  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
 110   *** This is not anymore true when the application runs on a kernel
 111       newer than approximately 2.1.60.
 112
 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.