You've already forked linux-packaging-mono
Imported Upstream version 3.12.1
Former-commit-id: ce565ca85f5d5abe367a12026a5712944dbf6319
This commit is contained in:
Jo Shields
@ -1,228 +0,0 @@
|
||||
<?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> (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
Block a user