1 Darwin/MacOSX Support - December 16, 2003
2 3 == Build Notes ==
4 5 Building can be done with autoconf as normal. If you want to build
6 a Universal library using autoconf, you need to disable dependency
7 tracking and specify your desired architectures in CFLAGS:
8 9 CFLAGS="-arch ppc -arch i386 -arch x86_64" ./configure --disable-dependency-tracking
10 11 12 == Important Usage Notes ==
13 14 GC_INIT() MUST be called before calling any other GC functions. This
15 is necessary to properly register segments in dynamic libraries. This
16 call is required even if you code does not use dynamic libraries as the
17 dyld code handles registering all data segments.
18 19 When your use of the garbage collector is confined to dylibs and you
20 cannot call GC_INIT() before your libraries' static initializers have
21 run and perhaps called GC_malloc(), create an initialization routine
22 for each library to call GC_INIT(), e.g.:
23 24 #include "gc.h"
25 extern "C" void my_library_init() { GC_INIT(); }
26 27 Compile this code into a my_library_init.o, and link it into your
28 dylib. When you link the dylib, pass the -init argument with
29 _my_library_init (e.g. gcc -dynamiclib -o my_library.dylib a.o b.o c.o
30 my_library_init.o -init _my_library_init). This causes
31 my_library_init() to be called before any static initializers, and
32 will initialize the garbage collector properly.
33 34 Note: It doesn't hurt to call GC_INIT() more than once, so it's best,
35 if you have an application or set of libraries that all use the
36 garbage collector, to create an initialization routine for each of
37 them that calls GC_INIT(). Better safe than sorry.
38 39 Thread-local GC allocation will not work with threads that are not
40 created using the GC-provided override of pthread_create(). Threads
41 created without the GC-provided pthread_create() do not have the
42 necessary data structures in the GC to store this data.
43 44 45 == Implementation Information ==
46 47 Darwin/MacOSX support is nearly complete. Thread support is reliable on
48 Darwin 6.x (MacOSX 10.2) and there have been reports of success on older
49 Darwin versions (MacOSX 10.1). Shared library support had also been
50 added and the gc can be run from a shared library.
51 52 Thread support is implemented in terms of mach thread_suspend and
53 thread_resume calls. These provide a very clean interface to thread
54 suspension. This implementation doesn't rely on pthread_kill so the
55 code works on Darwin < 6.0 (MacOSX 10.1). All the code to stop and
56 start the world is located in darwin_stop_world.c.
57 58 Since not all uses of the GC enable clients to override pthread_create()
59 before threads have been created, the code for stopping the world has
60 been rewritten to look for threads using Mach kernel calls. Each
61 thread identified in this way is suspended and resumed as above. In
62 addition, since Mach kernel threads do not contain pointers to their
63 stacks, a stack-walking function has been written to find the stack
64 limits. Given an initial stack pointer (for the current thread, a
65 pointer to a stack-allocated local variable will do; for a non-active
66 thread, we grab the value of register 1 (on PowerPC)), it
67 will walk the PPC Mach-O-ABI compliant stack chain until it reaches the
68 top of the stack. This appears to work correctly for GCC-compiled C,
69 C++, Objective-C, and Objective-C++ code, as well as for Java
70 programs that use JNI. If you run code that does not follow the stack
71 layout or stack pointer conventions laid out in the PPC Mach-O ABI,
72 then this will likely crash the garbage collector.
73 74 Mach has a very clean interface to exception handing. So, the current
75 implementation of the incremental collection uses Mach's exception handling.
76 77 Much thanks goes to Andrew Stone, Dietmar Planitzer, Andrew Begel,
78 Jeff Sturm, and Jesse Rosenstock for all their work on the
79 Darwin/OS X port.
80 81 -Brian Alliet
82