96 lines
2.4 KiB
HTML
96 lines
2.4 KiB
HTML
<h1>GC Handles</h1>
|
|
|
|
<h3>Synopsys</h3>
|
|
|
|
<div class="mapi-header">
|
|
@API_IDX@
|
|
</div>
|
|
|
|
<p>GC handles are wrappers that are used to keep references to
|
|
managed objects in the unmanaged space and preventing the
|
|
object from being disposed.
|
|
|
|
<p>These are the C equivalents of the <tt>System.GCHandle</tt>
|
|
structure.
|
|
|
|
<p>There are two kinds of GCHandles that can be created:
|
|
|
|
<ul>
|
|
<li>Handles to objects (use <tt><a
|
|
href="#api:mono_gchandle_new">mono_gchandle_new</a></tt>).
|
|
|
|
<li>Weak handles to objects (use <tt><a
|
|
href="#api:mono_gchandle_new_weakref">mono_gchandle_new_weakref</a></tt>).
|
|
Weak handles can have the objects reclaimed by the
|
|
garbage collector.
|
|
|
|
</ul>
|
|
|
|
<p>To retrieve the target address of an object pointed to by a
|
|
<tt>GCHandle</tt> you should use
|
|
<tt>mono_gchandle_get_target</tt>.
|
|
|
|
<p>For example, consider the following C code:
|
|
|
|
<div class="mapi-code">
|
|
static MonoObject* o = NULL;
|
|
</div>
|
|
|
|
<p>The object in `o' will *NOT* be scanned.
|
|
|
|
<p>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.
|
|
|
|
<div class="mapi-code">
|
|
guint32 handle = mono_gchandle_new (my_object, TRUE);
|
|
</div>
|
|
|
|
<p>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:
|
|
|
|
<div class="mapi-code">
|
|
MonoObject* obj = mono_gchandle_get_target (handle);
|
|
</div>
|
|
|
|
<p>When you don't need the handle anymore you need to call:
|
|
|
|
<div class="mapi-code">
|
|
mono_gchandle_free (handle);
|
|
</div>
|
|
|
|
<p>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.
|
|
|
|
<p>So code that looked like this:
|
|
|
|
<div class="mapi-code">
|
|
static MonoObject* obj = NULL;
|
|
...
|
|
obj = mono_object_new (...);
|
|
// use obj
|
|
...
|
|
// when done to allow the GC to collect obj
|
|
obj = NULL;
|
|
</div>
|
|
|
|
<p>should now be changed to:
|
|
|
|
<div class="mapi-code">
|
|
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);
|
|
</div>
|
|
|
|
<h4><a name="api:mono_gchandle_new">mono_gchandle_new</a></h4>
|
|
<h4><a name="api:mono_gchandle_new_weakref">mono_gchandle_new_weakref</a></h4>
|
|
<h4><a name="api:mono_gchandle_get_target">mono_gchandle_get_target</a></h4>
|
|
<h4><a name="api:mono_gchandle_free">mono_gchandle_free</a></h4>
|