351 lines
11 KiB
HTML
351 lines
11 KiB
HTML
<?xml version="1.0" encoding="utf-8"?>
|
|
<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-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 (GCObject *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> 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">guint32
|
|
mono_gchandle_new_weakref (GCObject *obj, gboolean 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</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">GCObject*
|
|
mono_gchandle_get_target (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</code> or <code>mono_gchandle_new_weakref</code>. <p /></div>
|
|
</div><!--mapi-description -->
|
|
</div><!--height container -->
|