GC Handles
Synopsys
GC handles are wrappers that are used to keep references to
managed objects in the unmanaged space and preventing the
object from being disposed.
These are the C equivalents of the
System.GCHandle
structure.
There are two kinds of GCHandles that can be created:
To retrieve the target address of an object pointed to by a
GCHandle you should use
mono_gchandle_get_target.
For example, consider the following C code:
static MonoObject* o = NULL;
The object in `o' will *NOT* be scanned.
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.
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* obj = NULL;
...
obj = mono_object_new (...);
// use obj
...
// when done to allow the GC to collect obj
obj = NULL;
should now be changed to:
static guint32 o_handle;
...
MonoObject *obj = mono_object_new (...);
o_handle = mono_gchandle_new (obj, TRUE);
// use o or mono_gchandle_get_target (o_handle)
...
// when done to allow the GC to collect obj
mono_gchandle_free (o_handle);
mono_gchandle_new
Syntax
guint32
mono_gchandle_new_internal (MonoObject *obj, gboolean pinned)
Parameters
| obj | managed object to get a handle for |
| pinned | whether the object should be pinned |
Return value
a handle that can be used to access the object from
unmanaged code.
Description
This returns a handle that wraps the object, this is used to keep a
reference to a managed object from the unmanaged world and preventing the
object from being disposed.
If
pinned is false the address of the object can not be obtained, if it is
true the address of the object can be obtained. This will also pin the
object so it will not be possible by a moving garbage collector to move the
object.
mono_gchandle_new_weakref
Syntax
uint32_t
mono_gchandle_new_weakref (MonoObject *obj, mono_bool track_resurrection)
Parameters
| obj | managed object to get a handle for |
| track_resurrection | Determines how long to track the object, if this is set to TRUE, the object is tracked after finalization, if FALSE, the object is only tracked up until the point of finalization. |
Return value
a handle that can be used to access the object from
unmanaged code.
Description
This returns a weak handle that wraps the object, this is used to
keep a reference to a managed object from the unmanaged world.
Unlike the
mono_gchandle_new_internal the object can be reclaimed by the
garbage collector. In this case the value of the GCHandle will be
set to zero.
If
track_resurrection is
TRUE the object will be tracked through
finalization and if the object is resurrected during the execution
of the finalizer, then the returned weakref will continue to hold
a reference to the object. If
track_resurrection is
FALSE, then
the weak reference's target will become
NULL as soon as the object
is passed on to the finalizer.
mono_gchandle_get_target
Syntax
MonoObject*
mono_gchandle_get_target_internal (guint32 gchandle)
Parameters
| gchandle | a GCHandle's handle. |
Return value
A pointer to the MonoObject* represented by the handle or
NULL for a collected object if using a weakref handle.
Description
The handle was previously created by calling
mono_gchandle_new_internal or
mono_gchandle_new_weakref.