mono/linux-packaging-mono
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
linux-packaging-mono/docs/deploy/mono-api-gchandle.html

228 lines
6.3 KiB
HTML
Raw Normal View History

Imported Upstream version 4.2.2.29 Former-commit-id: f069081cc0821095435a845c961ae61cbbc95121
2016-01-18 21:29:19 -05:00
<?xml version="1.0" encoding="utf-8"?><span>
Imported Upstream version 4.0.1 Former-commit-id: 6d37e02debfe41dd5c13ba6f6a2428c8b1ff5e28
2015-04-26 19:10:23 +01:00
<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> (MonoObject *obj,
gboolean pinned);
guint32 <a href="#api:mono_gchandle_new_weakref">mono_gchandle_new_weakref</a> (MonoObject *obj,
gboolean track_resurrection);
MonoObject* <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 (MonoObject *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 (MonoObject *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">MonoObject*
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>
Reference in New Issue Copy Permalink