1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
|
<?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 -->
|
