boehm-gc/README.linux

   1 See README.alpha for Linux on DEC AXP info.
   2
   3 This file applies mostly to Linux/Intel IA32.  Ports to Linux on an M68K
   4 and PowerPC are also integrated.  They should behave similarly, except that
   5 the PowerPC port lacks incremental GC support, and it is unknown to what
   6 extent the Linux threads code is functional.
   7
   8 Incremental GC is supported on Intel IA32 and M68K.
   9
  10 Dynamic libraries are supported on an ELF system.  A static executable
  11 should be linked with the gcc option "-Wl,-defsym,_DYNAMIC=0".
  12
  13 The collector appears to work with Linux threads.  We have seen
  14 intermittent hangs in sem_wait.  So far we have been unable to reproduce
  15 these unless the process was being debugged or traced.  Thus it's
  16 possible that the only real issue is that the debugger loses
  17 signals on rare occasions.
  18
  19 The garbage collector uses SIGPWR and SIGXCPU if it is used with
  20 Linux threads.  These should not be touched by the client program.
  21
  22 To use threads, you need to abide by the following requirements:
  23
  24 1) You need to use LinuxThreads (which are included in libc6).
  25
  26    The collector relies on some implementation details of the LinuxThreads
  27    package.  It is unlikely that this code will work on other
  28    pthread implementations (in particular it will *not* work with
  29    MIT pthreads).
  30
  31 2) You must compile the collector with -DLINUX_THREADS and -D_REENTRANT
  32    specified in the Makefile.
  33
  34 3a) Every file that makes thread calls should define LINUX_THREADS and
  35    _REENTRANT and then include gc.h.  Gc.h redefines some of the
  36    pthread primitives as macros which also provide the collector with
  37    information it requires.
  38
  39 3b) A new alternative to (3a) is to build the collector with
  40    -DUSE_LD_WRAP, and to link the final program with
  41
  42    (for ld) --wrap read --wrap dlopen --wrap pthread_create \
  43             --wrap pthread_join --wrap pthread_sigmask
  44
  45    (for gcc) -Wl,--wrap -Wl,read -Wl,--wrap -Wl,dlopen -Wl,--wrap \
  46              -Wl,pthread_create -Wl,--wrap -Wl,pthread_join -Wl,--wrap \
  47              -Wl,pthread_sigmask
  48
  49    In any case, _REENTRANT should be defined during compilation.
  50
  51 4) Dlopen() disables collection during its execution.  (It can't run
  52    concurrently with the collector, since the collector looks at its
  53    data structures.  It can't acquire the allocator lock, since arbitrary
  54    user startup code may run as part of dlopen().)  Under unusual
  55    conditions, this may cause unexpected heap growth.
  56
  57 5) The combination of LINUX_THREADS, REDIRECT_MALLOC, and incremental
  58    collection fails in seemingly random places.  This hasn't been tracked
  59    down yet, but is perhaps not completely astonishing.  The thread package
  60    uses malloc, and thus can presumably get SIGSEGVs while inside the
  61    package.  There is no real guarantee that signals are handled properly
  62    at that point.
  63
  64 6) Thread local storage may not be viewed as part of the root set by the
  65    collector.  This probably depends on the linuxthreads version.  For the
  66    time being, any collectable memory referenced by thread local storage should
  67    also be referenced from elsewhere, or be allocated as uncollectable.
  68    (This is really a bug that should be fixed somehow.)