gc-7.2/doc/README.darwin

   1 Darwin/MacOSX Support - December 16, 2003
   2 =========================================
   3
   4 Build Notes
   5 ===========
   6
   7 Building can be done with autoconf as normal. If you want to build
   8 a Universal library using autoconf, you need to disable dependency
   9 tracking and specify your desired architectures in CFLAGS:
  10
  11 CFLAGS="-arch ppc -arch i386 -arch x86_64" ./configure --disable-dependency-tracking
  12
  13
  14 Important Usage Notes
  15 =====================
  16
  17 GC_init() MUST be called before calling any other GC functions. This
  18 is necessary to properly register segments in dynamic libraries. This
  19 call is required even if you code does not use dynamic libraries as the
  20 dyld code handles registering all data segments.
  21
  22 When your use of the garbage collector is confined to dylibs and you
  23 cannot call GC_init() before your libraries' static initializers have
  24 run and perhaps called GC_malloc(), create an initialization routine
  25 for each library to call GC_init():
  26
  27 #include <gc/gc.h>
  28 extern "C" void my_library_init() { GC_init(); }
  29
  30 Compile this code into a my_library_init.o, and link it into your
  31 dylib. When you link the dylib, pass the -init argument with
  32 _my_library_init (e.g. gcc -dynamiclib -o my_library.dylib a.o b.o c.o
  33 my_library_init.o -init _my_library_init). This causes
  34 my_library_init() to be called before any static initializers, and
  35 will initialize the garbage collector properly.
  36
  37 Note: It doesn't hurt to call GC_init() more than once, so it's best,
  38 if you have an application or set of libraries that all use the
  39 garbage collector, to create an initialization routine for each of
  40 them that calls GC_init(). Better safe than sorry.
  41
  42 The incremental collector is still a bit flaky on darwin. It seems to
  43 work reliably with workarounds for a few possible bugs in place however
  44 these workaround may not work correctly in all cases. There may also
  45 be additional problems that I have not found.
  46
  47 Thread-local GC allocation will not work with threads that are not
  48 created using the GC-provided override of pthread_create(). Threads
  49 created without the GC-provided pthread_create() do not have the
  50 necessary data structures in the GC to store this data.
  51
  52
  53 Implementation Information
  54 ==========================
  55 Darwin/MacOSX support is nearly complete. Thread support is reliable on
  56 Darwin 6.x (MacOSX 10.2) and there have been reports of success on older
  57 Darwin versions (MacOSX 10.1). Shared library support had also been
  58 added and the gc can be run from a shared library.
  59
  60 Thread support is implemented in terms of mach thread_suspend and
  61 thread_resume calls. These provide a very clean interface to thread
  62 suspension. This implementation doesn't rely on pthread_kill so the
  63 code works on Darwin < 6.0 (MacOSX 10.1). All the code to stop and
  64 start the world is located in darwin_stop_world.c.
  65
  66 Since not all uses of the GC enable clients to override pthread_create()
  67 before threads have been created, the code for stopping the world has
  68 been rewritten to look for threads using Mach kernel calls. Each
  69 thread identified in this way is suspended and resumed as above. In
  70 addition, since Mach kernel threads do not contain pointers to their
  71 stacks, a stack-walking function has been written to find the stack
  72 limits. Given an initial stack pointer (for the current thread, a
  73 pointer to a stack-allocated local variable will do; for a non-active
  74 thread, we grab the value of register 1 (on PowerPC)), it
  75 will walk the PPC Mach-O-ABI compliant stack chain until it reaches the
  76 top of the stack. This appears to work correctly for GCC-compiled C,
  77 C++, Objective-C, and Objective-C++ code, as well as for Java
  78 programs that use JNI. If you run code that does not follow the stack
  79 layout or stack pointer conventions laid out in the PPC Mach-O ABI,
  80 then this will likely crash the garbage collector.
  81
  82 The original incremental collector support unfortunately no longer works
  83 on recent Darwin versions. It also relied on some undocumented kernel
  84 structures. Mach, however, does have a very clean interface to exception
  85 handing. The current implementation uses Mach's exception handling.
  86
  87 Much thanks goes to Andrew Stone, Dietmar Planitzer, Andrew Begel,
  88 Jeff Sturm, and Jesse Rosenstock for all their work on the
  89 Darwin/OS X port.
  90
  91 -Brian Alliet
  92 brian@brianweb.net
  93
  94 gc_cpp.h usage
  95 ==============
  96
  97 Replacement of operator new and delete is apparently not supported with
  98 dynamic libraries.  This means that applications using gc_cpp.h
  99 (including the built-in test) will probably not work correctly with
 100 the collector in a dynamic library, unless special care is taken.
 101
 102 See
 103 http://article.gmane.org/gmane.comp.programming.garbage-collection.boehmgc/1421
 104 for some details.
 105
 106 - Hans Boehm (based on information from Andrew Begel)
 107
 108
 109 Older Information (Most of this no longer applies to the current code)
 110 ======================================================================
 111
 112 While the GC should work on MacOS X Server, MacOS X and Darwin, I only tested
 113 it on MacOS X Server.
 114 I've added a PPC assembly version of GC_push_regs(), thus the setjmp() hack is
 115 no longer necessary. Incremental collection is supported via mprotect/signal.
 116 The current solution isn't really optimal because the signal handler must decode
 117 the faulting PPC machine instruction in order to find the correct heap address.
 118 Further, it must poke around in the register state which the kernel saved away
 119 in some obscure register state structure before it calls the signal handler -
 120 needless to say the layout of this structure is no where documented.
 121 Threads and dynamic libraries are not yet supported (adding dynamic library
 122 support via the low-level dyld API shouldn't be that hard).
 123
 124 The original MacOS X port was brought to you by Andrew Stone.
 125
 126
 127 June, 1 2000
 128
 129 Dietmar Planitzer
 130 dave.pl@ping.at
 131
 132 Note from Andrew Begel:
 133
 134 One more fix to enable gc.a to link successfully into a shared library for
 135 MacOS X. You have to add -fno-common to the CFLAGS in the Makefile. MacOSX
 136 disallows common symbols in anything that eventually finds its way into a
 137 shared library. (I don't completely understand why, but -fno-common seems to
 138 work and doesn't mess up the garbage collector's functionality).
 139
 140 Feb 26, 2003
 141
 142 Jeff Sturm and Jesse Rosenstock provided a patch that adds thread support.
 143 GC_MACOSX_THREADS should be defined in the build and in clients.  Real
 144 dynamic library support is still missing, i.e. dynamic library data segments
 145 are still not scanned.  Code that stores pointers to the garbage collected
 146 heap in statically allocated variables should not reside in a dynamic
 147 library.  This still doesn't appear to be 100% reliable.
 148
 149 Mar 10, 2003
 150 Brian Alliet contributed dynamic library support for MacOSX.  It could also
 151 use more testing.