diff options
author | Paolo Molaro <lupus@oddwiz.org> | 2004-07-07 14:17:05 +0400 |
---|---|---|
committer | Paolo Molaro <lupus@oddwiz.org> | 2004-07-07 14:17:05 +0400 |
commit | 6d42d62ae50277fc93ea780dfd59644037bba3b4 (patch) | |
tree | 4296ca5f38495cda5474da76f25eee25f154b0e5 /docs | |
parent | 58c4a474da33857dff462f16e506142253accc84 (diff) |
Rewrote to explain how things are done and why.
Removed misleading and incorrect info.
svn path=/trunk/mono/; revision=30831
Diffstat (limited to 'docs')
-rw-r--r-- | docs/gc-variables-in-c | 86 |
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 ------------------- |