Rewrote to explain how things are done and why.

Removed misleading and incorrect info.

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

1 files changed, 73 insertions, 13 deletions

diff --git a/docs/gc-variables-in-c b/docs/gc-variables-in-c
index 004b1aefa51..0146dcb4d24 100644
--- a/docs/gc-variables-in-c
+++ b/docs/gc-variables-in-c
@@ -1,14 +1,16 @@
-**THIS IS A WORK IN PROGRESS**
+		Handling GC allocated objects in C
 
-As part of an effort to improve our GC effort, we will be
-moving towards flagging every variable that the GC must know
-about. Previously, global C variables were considered GC roots.
-However, as a part of this effort, we can no longer cast such
-a wide net. We must explicitly declare roots in C code.
+As part of an effort to improve our GC, we need to keep track
+precisely of where objects are stored, so we can incrementally move
+from the current conservative GC to a more advanced precise and moving GC.
+Previously, all global C variables were considered GC roots, but this makes
+the GC less efficient and increases the chances false references are found
+to GC memory, hence retaining more memory than needed.
+We need to tell the GC that some object is supposed to be kept alive
+as if it was referenced in a global variable.
 
-Storing GC allocated objects in C
-For embeders and Mono VM developers
-------------------------------------
+For Mono embedders
+------------------
 
 In C#, if you say:
 class T {
@@ -24,10 +26,62 @@ static MonoObject* o = NULL;
 
 The object in `o' will *NOT* be scanned.
 
-If you need a C variable to be included in the GC's root set, you
-must do the following registration:
+If you need to store an object in a C variable and prevent it from being 
+collected, you need to acquire a GC handle for it.
 
-	MONO_GC_REGISTER_ROOT (my_object);
+	guint32 handle = mono_gchandle_new (my_object, TRUE);
+
+TRUE means the object will be pinned, so it won't move in memory 
+when we'll use a moving GC. You can access the MonoObject* referenced by
+a handle with:
+
+	MonoObject* obj = mono_gchandle_get_target (handle);
+
+When you don't need the handle anymore you need to call:
+
+	mono_gchandle_free (handle);
+
+Note that if you assign a new object to the C var, you need to get a new 
+handle, it's not enough to store a new object in the C var.
+
+So code that looked like this:
+
+	static MonoObject* o = NULL;
+	...
+	o = mono_object_new (...);
+	/* use o */
+	...
+	/* when done to allow the GC to collect o */
+	o = NULL;
+
+should now be changed to:
+
+	static guint32 o_handle;
+	...
+	MonoObject *o = mono_object_new (...);
+	o_handle = mono_gchandle_new (o, TRUE);
+	/* use o or mono_gchandle_get_target (o_handle) */
+	...
+	/* when done to allow the GC to collect o */
+	mono_gchandle_free (o_handle);
+
+
+For Mono runtime developers
+---------------------------
+
+There are two kinds of static vars used to store pointers to GC memory 
+that we need to consider:
+*) objects
+*) other memory chunks allocated with GC_MALLOC().
+
+Objects should be dealt with the GC handle support as detailed above.
+Other items should register the static pointer as an area to be considered
+part of the root set with the following:
+
+	static gpointer my_gc_data = NULL;
+	...
+	MONO_GC_REGISTER_ROOT (my_gc_data);
+	my_gc_data = GC_MALLOC (...);
 	
 Note that this registration is not necessary for *LOCAL* variables,
 as they are stored on the stack. It is only necessary for global variables,
@@ -35,8 +89,14 @@ as they are not a part of the GC's root set.
 
 Once you have done the MONO_GC_REGISTER_ROOT, the variable is just like
 a static variable in C#. To keep an object alive, you have the variable reference
-that object, to remove the reference, set the variable to NULL.
+the GC memory, to remove the reference, set the variable to NULL.
+
+As we prepare the code for a precise GC, GC_MALLOC () will not be used anymore
+in this way in most cases: we'll have a mechanism to specify exactly where
+references to GC memory is stored.
 
+[The rest of this file is useless, just kept until the switchover 
+of the internals is complete.]
 Mono Internal Audit
 -------------------