mono/docs/gc-issues

* GC issues you need to be careful about when hacking on the mono runtime.

mono currently uses the Boehm garbage collection library. This is a conservative
GC package: this means that the memory is searched for possible memory references
to chunks allocated with the GC. Not all the memory is searched, but only the memory
allocated with the GC itself (unless you use the 'atomic' variant of the allocation 
routines), the stack and global variables. Also, if the last reference to an object 
is stored in an area of themory that is not searched, the object may be freed resulting 
in memory corruption ind segfaults.

In particular, memory allocated with system's malloc() is not searched, so you need to be
careful NOT to store object references in memory allocated with malloc() (unless you are sure
that the object reference will be live at the same time in some other area under the control 
of the GC (on the stack or in a global variable, for example). Since g_malloc()
ultimately calls system malloc() the data structures in GLib are not safe to
use to store object references.

Occasionally, you'll need to store some object reference from C code: in this case, 
you must make sure that the store location is searched by the GC. You can safely
use thread local storage areas, global variables, stack variables. If you need a more 
complicated data structure, you can use a hash table: MonoGHashTable.
This hash table has the same interface as GHashTable from GLib, just stick the "mono_"
prefix in function calls and the "Mono" prefix in the hash table type name.
This hash table ensures that object references stored in it are tracked by the GC, as long
as the pointer to the hash is tracked itself.

Other data structures that are allocated with the GC and are safe to use to store pointers
to GC-allocated memory, are MonoDomain (keeps track of many domain specfic objects)
and MonoVTable (referenced by MonoDomain: keeps track of the static data of a type
since that can hold references to objects).