Return to README.linux CVS log

Up to [local] / OpenXM_contrib / gc

Annotation of OpenXM_contrib/gc/README.linux, Revision 1.1.1.2

1.1       maekawa     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:
1.1.1.2 ! maekawa    34: 3a) Every file that makes thread calls should define LINUX_THREADS and
1.1       maekawa    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:
1.1.1.2 ! maekawa    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.
1.1       maekawa    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.
1.1.1.2 ! maekawa    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.)