Added the docs dir to the dist (with a new doc on GC issues).

Removed defunct wrapper dir.
Fixed make distcheck in jit.
Really build monoburg if needed.

svn path=/trunk/mono/; revision=3492

1 files changed, 31 insertions, 0 deletions

diff --git a/docs/gc-issues b/docs/gc-issues
new file mode 100644
index 00000000000..95062c56244
--- /dev/null
+++ b/docs/gc-issues
@@ -0,0 +1,31 @@
+* 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).
+