228 lines
6.3 KiB
HTML
228 lines
6.3 KiB
HTML
<?xml version="1.0" encoding="utf-8"?><span>
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>mono-api-gchandle.html</title>
|
|
<style type="text/css">
|
|
|
|
|
|
h3 {
|
|
font-size: 18px;
|
|
padding-bottom: 4pt;
|
|
border-bottom: 2px solid #dddddd;
|
|
}
|
|
|
|
.api {
|
|
border: 1px solid;
|
|
padding: 10pt;
|
|
margin: 10pt;
|
|
}
|
|
|
|
.api-entry {
|
|
border-bottom: none;
|
|
font-size: 18px;
|
|
}
|
|
|
|
.prototype {
|
|
border: 1px solid;
|
|
background-color: #f2f2f2;
|
|
padding: 5pt;
|
|
margin-top: 5pt;
|
|
margin-bottom: 5pt;
|
|
}
|
|
|
|
.header {
|
|
border: 1px solid;
|
|
padding: 0 0 5pt 5pt;
|
|
margin: 10pt;
|
|
white-space: pre;
|
|
font-family: monospace;
|
|
}
|
|
|
|
.code {
|
|
border: 1px solid;
|
|
padding: 0 0 5pt 5pt;
|
|
margin: 10pt;
|
|
white-space: pre;
|
|
font-family: monospace;
|
|
}
|
|
|
|
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<h1>GC Handles</h1>
|
|
|
|
<h3>Synopsys</h3>
|
|
|
|
<div class="header">
|
|
guint32 <a href="#api:mono_gchandle_new">mono_gchandle_new</a> (GCObject *obj,
|
|
gboolean pinned);
|
|
guint32 <a href="#api:mono_gchandle_new_weakref">mono_gchandle_new_weakref</a> (GCObject *obj,
|
|
gboolean track_resurrection);
|
|
GCObject* <a href="#api:mono_gchandle_get_target">mono_gchandle_get_target</a> (guint32 gchandle);
|
|
void <a href="#api:mono_gchandle_free">mono_gchandle_free</a> (guint32 gchandle);
|
|
|
|
</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.
|
|
|
|
</li></li></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>
|
|
|
|
<a name="api:mono_gchandle_new"></a>
|
|
<div class="api">
|
|
<div class="api-entry">mono_gchandle_new</div>
|
|
|
|
<div class="prototype">guint32
|
|
mono_gchandle_new (GCObject *obj, gboolean pinned)
|
|
|
|
</div>
|
|
<p />
|
|
<b>Parameters</b>
|
|
<blockquote><dt><i>obj:</i></dt><dd> managed object to get a handle for</dd><dt><i>pinned:</i></dt><dd> whether the object should be pinned</dd></blockquote>
|
|
<b>Returns</b>
|
|
<blockquote> a handle that can be used to access the object from
|
|
|
|
unmanaged code.</blockquote>
|
|
<b>Remarks</b>
|
|
<p />
|
|
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.
|
|
|
|
<p />
|
|
If <i>pinned</i> 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.
|
|
|
|
<p />
|
|
|
|
</div> <a name="api:mono_gchandle_new_weakref"></a>
|
|
<div class="api">
|
|
<div class="api-entry">mono_gchandle_new_weakref</div>
|
|
|
|
<div class="prototype">guint32
|
|
mono_gchandle_new_weakref (GCObject *obj, gboolean track_resurrection)
|
|
|
|
</div>
|
|
<p />
|
|
<b>Parameters</b>
|
|
<blockquote><dt><i>obj:</i></dt><dd> managed object to get a handle for</dd><dt><i>pinned:</i></dt><dd> whether the object should be pinned</dd></blockquote>
|
|
<b>Returns</b>
|
|
<blockquote> a handle that can be used to access the object from
|
|
|
|
unmanaged code.</blockquote>
|
|
<b>Remarks</b>
|
|
<p />
|
|
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 the object can be reclaimed by the
|
|
garbage collector. In this case the value of the GCHandle will be
|
|
set to zero.
|
|
|
|
<p />
|
|
If <i>pinned</i> 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.
|
|
|
|
<p />
|
|
|
|
</div> <a name="api:mono_gchandle_get_target"></a>
|
|
<div class="api">
|
|
<div class="api-entry">mono_gchandle_get_target</div>
|
|
|
|
<div class="prototype">GCObject*
|
|
mono_gchandle_get_target (guint32 gchandle)
|
|
|
|
</div>
|
|
<p />
|
|
<b>Parameters</b>
|
|
<blockquote><dt><i>gchandle:</i></dt><dd> a GCHandle's handle.</dd></blockquote>
|
|
<b>Remarks</b>
|
|
<p />
|
|
The handle was previously created by calling mono_gchandle_new or
|
|
mono_gchandle_new_weakref.
|
|
|
|
Returns a pointer to the MonoObject represented by the handle or
|
|
NULL for a collected object if using a weakref handle.
|
|
|
|
</div></body>
|
|
</html>
|
|
</span> |