390 lines
11 KiB
HTML
390 lines
11 KiB
HTML
<?xml version="1.0" encoding="us-ascii"?>
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>mono-api-gchandle.html</title>
|
|
<style type="text/css">
|
|
.mapi-docs {
|
|
line-height: 1.5;
|
|
padding-left: 2em;
|
|
padding-right: 2em;
|
|
}
|
|
.mapi-docs p {
|
|
max-width: 60em;
|
|
}
|
|
.mapi-docs .mapi-body {
|
|
max-width: 60em;
|
|
}
|
|
.mapi-docs code {
|
|
border: 1px solid rgba(214,214,214,1);
|
|
background-color: rgba(249,249,249,1);
|
|
padding: 0.1em 0.5em;
|
|
}
|
|
.mapi-description code {
|
|
font-family: "Consolas", "Courier", monospace;
|
|
border: 1px solid rgba(214,214,214,1);
|
|
background-color: rgba(249,249,249,1);
|
|
padding: 0.1em 0.2em;
|
|
}
|
|
|
|
.mapi-header {
|
|
padding: 0 0 5pt 5pt;
|
|
margin: 10pt;
|
|
white-space: pre;
|
|
font-family: monospace;
|
|
border: 1px solid rgba(233,233,233,1);
|
|
background-color: rgba(249,249,249,1);
|
|
}
|
|
|
|
.mapi-code {
|
|
padding: 5pt 5pt;
|
|
margin: 10pt;
|
|
white-space: pre;
|
|
font-family: monospace;
|
|
border: 1px solid rgba(233,233,233,1);
|
|
background-color: rgba(249,249,249,1);
|
|
}
|
|
|
|
.mapi-code:first-line {
|
|
line-height: 0px;
|
|
}
|
|
|
|
.mapi-codeblock {
|
|
display: block;
|
|
padding: 5pt 5pt;
|
|
margin: 10pt;
|
|
white-space: pre;
|
|
font-family: monospace;
|
|
border: 1px solid rgba(233,233,233,1);
|
|
background-color: rgba(249,249,249,1);
|
|
}
|
|
|
|
.mapi-entry code {
|
|
border: none;
|
|
background-color: transparent;
|
|
}
|
|
|
|
.mapi-parameters {
|
|
border-collapse: collapse;
|
|
border-spacing: 0;
|
|
empty-cells: hide;
|
|
border: 0;
|
|
margin: 5px 0 26px;
|
|
}
|
|
|
|
.mapi-parameters td {
|
|
border: 1px solid rgba(214,214,214,1);
|
|
border-left-style: none;
|
|
padding: 5px 25px 5px 10px;
|
|
}
|
|
|
|
.mapi-parameters tr>td:last-child {
|
|
border-right: 0;
|
|
}
|
|
|
|
.mapi-parameters td:first-of-type {
|
|
text-align: right;
|
|
padding: 7px;
|
|
vertical-align: top;
|
|
word-break: normal;
|
|
width: 40px;
|
|
}
|
|
|
|
.mapi-parameters tr:last-child>td {
|
|
border-bottom: 0;
|
|
}
|
|
|
|
.mapi-parameters tr:first-child>td {
|
|
border-top: 0;
|
|
}
|
|
|
|
.mapi-parameters tr td:first-of-type {
|
|
text-align: right;
|
|
padding: 7px;
|
|
vertical-align: top;
|
|
word-break: normal;
|
|
width: 40px;
|
|
}
|
|
|
|
.mapi {
|
|
left: -25px;
|
|
margin: 0;
|
|
padding: 13px 25px 0;
|
|
position: relative;
|
|
width: 100%;
|
|
}
|
|
|
|
.mapi-description {
|
|
background: rgba(249,249,249,1);
|
|
border-bottom: 1px solid rgba(233,233,233,1);
|
|
left: -25px;
|
|
margin: 0;
|
|
padding: 13px 25px 0;
|
|
position: relative;
|
|
width: 100%;
|
|
}
|
|
|
|
.mapi-entry {
|
|
background: transparent;
|
|
}
|
|
|
|
.mapi-docs {
|
|
}
|
|
|
|
.mapi-prototype {
|
|
border-left: 5px solid rgba(205,233,244,1);
|
|
padding: .5em;
|
|
margin-top: 5pt;
|
|
margin-bottom: 5pt;
|
|
font-family: "Consolas", "Courier", monospace;
|
|
display: block;
|
|
overflow: auto;
|
|
background-color: #f9f9f9;
|
|
}
|
|
|
|
.mapi-declaration {
|
|
margin-top: 21px;
|
|
}
|
|
|
|
.mapi-section {
|
|
font-size: smaller;
|
|
font-weight: bold;
|
|
margin-top: 21px;
|
|
line-height: 1.5;
|
|
}
|
|
|
|
.mapi-strike {
|
|
text-decoration: line-through;
|
|
}
|
|
|
|
.mapi-deprecated {
|
|
color: red;
|
|
}
|
|
|
|
.mapi-ptr-container {
|
|
background: white;
|
|
border-bottom: 1px solid rgba(233,233,233,1);
|
|
left: -25px;
|
|
padding-left: 25px;
|
|
padding-right: 25px;
|
|
padding-bottom: 13px;
|
|
position: relative;
|
|
width: 100%;
|
|
}
|
|
|
|
.mapi-ptr {
|
|
background: rgba(249,249,249,1);
|
|
border-left: 1px solid rgba(233,233,233,1);
|
|
border-top: 1px solid rgba(233,233,233,1);
|
|
height: 12px;
|
|
left: 37px;
|
|
top: -7px;
|
|
-webkit-transform: rotate(45deg);
|
|
-moz-transform: rotate(45deg);
|
|
-o-transform: rotate(45deg);
|
|
transform: rotate(45deg);
|
|
position: absolute;
|
|
width: 12px;
|
|
}
|
|
|
|
.mapi-height-container {
|
|
left: -25px;
|
|
padding: 0 25px;
|
|
position: relative;
|
|
width: 100%;
|
|
}
|
|
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<div class="mapi-docs">
|
|
<h1>GC Handles</h1>
|
|
|
|
<h3>Synopsys</h3>
|
|
|
|
<div class="mapi-header">
|
|
|
|
</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="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>
|
|
|
|
<a name="api:mono_gchandle_new"></a>
|
|
<div class="mapi">
|
|
<div class="mapi-entry "><code>mono_gchandle_new</code></div>
|
|
<div class="mapi-height-container">
|
|
<div class="mapi-ptr-container"></div>
|
|
<div class="mapi-description">
|
|
<div class="mapi-ptr"></div>
|
|
|
|
<div class="mapi-declaration mapi-section">Syntax</div>
|
|
<div class="mapi-prototype">guint32
|
|
mono_gchandle_new_internal (MonoObject *obj, gboolean pinned)
|
|
|
|
</div>
|
|
<p />
|
|
<div class="mapi-section">Parameters</div>
|
|
<table class="mapi-parameters"><tbody><tr><td><i>obj</i></td><td> managed object to get a handle for</td></tr><tr><td><i>pinned</i></td><td> whether the object should be pinned</td></tr></tbody></table> <div class="mapi-section">Return value</div>
|
|
<div> a handle that can be used to access the object from
|
|
|
|
unmanaged code.</div>
|
|
<div class="mapi-section">Description</div>
|
|
<div>
|
|
<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>
|
|
</div><!--mapi-description -->
|
|
</div><!--height container -->
|
|
</div> <!-- class=mapi -->
|
|
|
|
<a name="api:mono_gchandle_new_weakref"></a>
|
|
<div class="mapi">
|
|
<div class="mapi-entry "><code>mono_gchandle_new_weakref</code></div>
|
|
<div class="mapi-height-container">
|
|
<div class="mapi-ptr-container"></div>
|
|
<div class="mapi-description">
|
|
<div class="mapi-ptr"></div>
|
|
|
|
<div class="mapi-declaration mapi-section">Syntax</div>
|
|
<div class="mapi-prototype">uint32_t
|
|
mono_gchandle_new_weakref (MonoObject *obj, mono_bool track_resurrection)
|
|
|
|
</div>
|
|
<p />
|
|
<div class="mapi-section">Parameters</div>
|
|
<table class="mapi-parameters"><tbody><tr><td><i>obj</i></td><td> managed object to get a handle for</td></tr><tr><td><i>track_resurrection</i></td><td> Determines how long to track the object, if this is set to <code>TRUE</code>, the object is tracked after finalization, if <code>FALSE</code>, the object is only tracked up until the point of finalization.</td></tr></tbody></table> <div class="mapi-section">Return value</div>
|
|
<div> a handle that can be used to access the object from
|
|
|
|
unmanaged code.</div>
|
|
<div class="mapi-section">Description</div>
|
|
<div>
|
|
<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 <code>mono_gchandle_new_internal</code> 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>track_resurrection</i> is <code>TRUE</code> the object will be tracked through
|
|
finalization and if the object is resurrected during the execution
|
|
of the finalizer, then the returned weakref will continue to hold
|
|
a reference to the object. If <i>track_resurrection</i> is <code>FALSE</code>, then
|
|
the weak reference's target will become <code>NULL</code> as soon as the object
|
|
is passed on to the finalizer.
|
|
<p /></div>
|
|
</div><!--mapi-description -->
|
|
</div><!--height container -->
|
|
</div> <!-- class=mapi -->
|
|
|
|
<a name="api:mono_gchandle_get_target"></a>
|
|
<div class="mapi">
|
|
<div class="mapi-entry "><code>mono_gchandle_get_target</code></div>
|
|
<div class="mapi-height-container">
|
|
<div class="mapi-ptr-container"></div>
|
|
<div class="mapi-description">
|
|
<div class="mapi-ptr"></div>
|
|
|
|
<div class="mapi-declaration mapi-section">Syntax</div>
|
|
<div class="mapi-prototype">MonoObject*
|
|
mono_gchandle_get_target_internal (guint32 gchandle)
|
|
|
|
</div>
|
|
<p />
|
|
<div class="mapi-section">Parameters</div>
|
|
<table class="mapi-parameters"><tbody><tr><td><i>gchandle</i></td><td> a GCHandle's handle.</td></tr></tbody></table> <div class="mapi-section">Return value</div>
|
|
<div> A pointer to the <code>MonoObject*</code> represented by the handle or
|
|
|
|
<code>NULL</code> for a collected object if using a weakref handle.</div>
|
|
<div class="mapi-section">Description</div>
|
|
<div>
|
|
<p />
|
|
The handle was previously created by calling <code>mono_gchandle_new_internal</code> or
|
|
<code>mono_gchandle_new_weakref</code>.
|
|
<p /></div>
|
|
</div><!--mapi-description -->
|
|
</div><!--height container -->
|