| 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(): |
| 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 |
The incremental collector is still a bit flaky on darwin. It seems to |
| 40 |
work reliably with workarounds for a few possible bugs in place however |
| 41 |
these workaround may not work correctly in all cases. There may also |
| 42 |
be additional problems that I have not found. |
| 43 |
|
| 44 |
Thread-local GC allocation will not work with threads that are not |
| 45 |
created using the GC-provided override of pthread_create(). Threads |
| 46 |
created without the GC-provided pthread_create() do not have the |
| 47 |
necessary data structures in the GC to store this data. |
| 48 |
|
| 49 |
|
| 50 |
== Implementation Information == |
| 51 |
|
| 52 |
Darwin/MacOSX support is nearly complete. Thread support is reliable on |
| 53 |
Darwin 6.x (MacOSX 10.2) and there have been reports of success on older |
| 54 |
Darwin versions (MacOSX 10.1). Shared library support had also been |
| 55 |
added and the gc can be run from a shared library. |
| 56 |
|
| 57 |
Thread support is implemented in terms of mach thread_suspend and |
| 58 |
thread_resume calls. These provide a very clean interface to thread |
| 59 |
suspension. This implementation doesn't rely on pthread_kill so the |
| 60 |
code works on Darwin < 6.0 (MacOSX 10.1). All the code to stop and |
| 61 |
start the world is located in darwin_stop_world.c. |
| 62 |
|
| 63 |
Since not all uses of the GC enable clients to override pthread_create() |
| 64 |
before threads have been created, the code for stopping the world has |
| 65 |
been rewritten to look for threads using Mach kernel calls. Each |
| 66 |
thread identified in this way is suspended and resumed as above. In |
| 67 |
addition, since Mach kernel threads do not contain pointers to their |
| 68 |
stacks, a stack-walking function has been written to find the stack |
| 69 |
limits. Given an initial stack pointer (for the current thread, a |
| 70 |
pointer to a stack-allocated local variable will do; for a non-active |
| 71 |
thread, we grab the value of register 1 (on PowerPC)), it |
| 72 |
will walk the PPC Mach-O-ABI compliant stack chain until it reaches the |
| 73 |
top of the stack. This appears to work correctly for GCC-compiled C, |
| 74 |
C++, Objective-C, and Objective-C++ code, as well as for Java |
| 75 |
programs that use JNI. If you run code that does not follow the stack |
| 76 |
layout or stack pointer conventions laid out in the PPC Mach-O ABI, |
| 77 |
then this will likely crash the garbage collector. |
| 78 |
|
| 79 |
The original incremental collector support unfortunately no longer works |
| 80 |
on recent Darwin versions. It also relied on some undocumented kernel |
| 81 |
structures. Mach, however, does have a very clean interface to exception |
| 82 |
handing. The current implementation uses Mach's exception handling. |
| 83 |
|
| 84 |
Much thanks goes to Andrew Stone, Dietmar Planitzer, Andrew Begel, |
| 85 |
Jeff Sturm, and Jesse Rosenstock for all their work on the |
| 86 |
Darwin/OS X port. |
| 87 |
|
| 88 |
-Brian Alliet |
| 89 |
|
| 90 |
== gc_cpp.h usage == |
| 91 |
|
| 92 |
Replacement of operator new and delete is apparently not supported with |
| 93 |
dynamic libraries. This means that applications using gc_cpp.h |
| 94 |
(including the built-in test) will probably not work correctly with |
| 95 |
the collector in a dynamic library, unless special care is taken. |
| 96 |
|
| 97 |
See |
| 98 |
http://article.gmane.org/gmane.comp.programming.garbage-collection.boehmgc/1421 |
| 99 |
for some details. |
| 100 |
|
| 101 |
- Hans Boehm (based on information from Andrew Begel) |
| 102 |
|
| 103 |
|
| 104 |
== Older Information (Most of this no longer applies to the current code) == |
| 105 |
|
| 106 |
While the GC should work on MacOS X Server, MacOS X and Darwin, I only tested |
| 107 |
it on MacOS X Server. |
| 108 |
I've added a PPC assembly version of GC_push_regs(), thus the setjmp() hack is |
| 109 |
no longer necessary. Incremental collection is supported via mprotect/signal. |
| 110 |
The current solution isn't really optimal because the signal handler must decode |
| 111 |
the faulting PPC machine instruction in order to find the correct heap address. |
| 112 |
Further, it must poke around in the register state which the kernel saved away |
| 113 |
in some obscure register state structure before it calls the signal handler - |
| 114 |
needless to say the layout of this structure is no where documented. |
| 115 |
Threads and dynamic libraries are not yet supported (adding dynamic library |
| 116 |
support via the low-level dyld API shouldn't be that hard). |
| 117 |
|
| 118 |
The original MacOS X port was brought to you by Andrew Stone. |
| 119 |
|
| 120 |
|
| 121 |
June, 1 2000 |
| 122 |
|
| 123 |
Dietmar Planitzer |
| 124 |
|
| 125 |
Note from Andrew Begel: |
| 126 |
|
| 127 |
One more fix to enable gc.a to link successfully into a shared library for |
| 128 |
MacOS X. You have to add -fno-common to the CFLAGS in the Makefile. MacOSX |
| 129 |
disallows common symbols in anything that eventually finds its way into a |
| 130 |
shared library. (I don't completely understand why, but -fno-common seems to |
| 131 |
work and doesn't mess up the garbage collector's functionality). |
| 132 |
|
| 133 |
Feb 26, 2003 |
| 134 |
|
| 135 |
Jeff Sturm and Jesse Rosenstock provided a patch that adds thread support. |
| 136 |
GC_THREADS should be defined in the build and in clients. Real |
| 137 |
dynamic library support is still missing, i.e. dynamic library data segments |
| 138 |
are still not scanned. Code that stores pointers to the garbage collected |
| 139 |
heap in statically allocated variables should not reside in a dynamic |
| 140 |
library. This still doesn't appear to be 100% reliable. |
| 141 |
|
| 142 |
Mar 10, 2003 |
| 143 |
Brian Alliet contributed dynamic library support for MacOSX. It could also |
| 144 |
use more testing. |