<h1>GC Handles</h1>

<h3>Synopsys</h3>

	<div class="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="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="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="code">
        MonoObject* obj = mono_gchandle_get_target (handle);
</div>

	<p>When you don't need the handle anymore you need to call:

<div class="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="code">
        static MonoObject* o = NULL;
        ...
        o = mono_object_new (...);
        /* use o */
        ...
        /* when done to allow the GC to collect o */
        o = NULL;
</div>

	<p>should now be changed to:

<div class="code">
        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);
</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>