Debian Codegraph @

docs/deploy/mono-api-gchandle.html

raw
1 <?xml version="1.0" encoding="us-ascii"?>
2 <html xmlns="http://www.w3.org/1999/xhtml">
3 <head>
4 <title>mono-api-gchandle.html</title>
5 <style type="text/css">
6 .mapi-docs {
7 line-height: 1.5;
8 padding-left: 2em;
9 padding-right: 2em;
10 }
11 .mapi-docs p {
12 max-width: 60em;
13 }
14 .mapi-docs .mapi-body {
15 max-width: 60em;
16 }
17 .mapi-docs code {
18 border: 1px solid rgba(214,214,214,1);
19 background-color: rgba(249,249,249,1);
20 padding: 0.1em 0.5em;
21 }
22 .mapi-description code {
23 font-family: "Consolas", "Courier", monospace;
24 border: 1px solid rgba(214,214,214,1);
25 background-color: rgba(249,249,249,1);
26 padding: 0.1em 0.2em;
27 }
28
29 .mapi-header {
30 padding: 0 0 5pt 5pt;
31 margin: 10pt;
32 white-space: pre;
33 font-family: monospace;
34 border: 1px solid rgba(233,233,233,1);
35 background-color: rgba(249,249,249,1);
36 }
37
38 .mapi-code {
39 padding: 5pt 5pt;
40 margin: 10pt;
41 white-space: pre;
42 font-family: monospace;
43 border: 1px solid rgba(233,233,233,1);
44 background-color: rgba(249,249,249,1);
45 }
46
47 .mapi-code:first-line {
48 line-height: 0px;
49 }
50
51 .mapi-codeblock {
52 display: block;
53 padding: 5pt 5pt;
54 margin: 10pt;
55 white-space: pre;
56 font-family: monospace;
57 border: 1px solid rgba(233,233,233,1);
58 background-color: rgba(249,249,249,1);
59 }
60
61 .mapi-entry code {
62 border: none;
63 background-color: transparent;
64 }
65
66 .mapi-parameters {
67 border-collapse: collapse;
68 border-spacing: 0;
69 empty-cells: hide;
70 border: 0;
71 margin: 5px 0 26px;
72 }
73
74 .mapi-parameters td {
75 border: 1px solid rgba(214,214,214,1);
76 border-left-style: none;
77 padding: 5px 25px 5px 10px;
78 }
79
80 .mapi-parameters tr>td:last-child {
81 border-right: 0;
82 }
83
84 .mapi-parameters td:first-of-type {
85 text-align: right;
86 padding: 7px;
87 vertical-align: top;
88 word-break: normal;
89 width: 40px;
90 }
91
92 .mapi-parameters tr:last-child>td {
93 border-bottom: 0;
94 }
95
96 .mapi-parameters tr:first-child>td {
97 border-top: 0;
98 }
99
100 .mapi-parameters tr td:first-of-type {
101 text-align: right;
102 padding: 7px;
103 vertical-align: top;
104 word-break: normal;
105 width: 40px;
106 }
107
108 .mapi {
109 left: -25px;
110 margin: 0;
111 padding: 13px 25px 0;
112 position: relative;
113 width: 100%;
114 }
115
116 .mapi-description {
117 background: rgba(249,249,249,1);
118 border-bottom: 1px solid rgba(233,233,233,1);
119 left: -25px;
120 margin: 0;
121 padding: 13px 25px 0;
122 position: relative;
123 width: 100%;
124 }
125
126 .mapi-entry {
127 background: transparent;
128 }
129
130 .mapi-docs {
131 }
132
133 .mapi-prototype {
134 border-left: 5px solid rgba(205,233,244,1);
135 padding: .5em;
136 margin-top: 5pt;
137 margin-bottom: 5pt;
138 font-family: "Consolas", "Courier", monospace;
139 display: block;
140 overflow: auto;
141 background-color: #f9f9f9;
142 }
143
144 .mapi-declaration {
145 margin-top: 21px;
146 }
147
148 .mapi-section {
149 font-size: smaller;
150 font-weight: bold;
151 margin-top: 21px;
152 line-height: 1.5;
153 }
154
155 .mapi-strike {
156 text-decoration: line-through;
157 }
158
159 .mapi-deprecated {
160 color: red;
161 }
162
163 .mapi-ptr-container {
164 background: white;
165 border-bottom: 1px solid rgba(233,233,233,1);
166 left: -25px;
167 padding-left: 25px;
168 padding-right: 25px;
169 padding-bottom: 13px;
170 position: relative;
171 width: 100%;
172 }
173
174 .mapi-ptr {
175 background: rgba(249,249,249,1);
176 border-left: 1px solid rgba(233,233,233,1);
177 border-top: 1px solid rgba(233,233,233,1);
178 height: 12px;
179 left: 37px;
180 top: -7px;
181 -webkit-transform: rotate(45deg);
182 -moz-transform: rotate(45deg);
183 -o-transform: rotate(45deg);
184 transform: rotate(45deg);
185 position: absolute;
186 width: 12px;
187 }
188
189 .mapi-height-container {
190 left: -25px;
191 padding: 0 25px;
192 position: relative;
193 width: 100%;
194 }
195
196 </style>
197 </head>
198 <body>
199 <div class="mapi-docs">
200 <h1>GC Handles</h1>
201
202 <h3>Synopsys</h3>
203
204 <div class="mapi-header">
205
206 </div>
207
208 <p />GC handles are wrappers that are used to keep references to
209 managed objects in the unmanaged space and preventing the
210 object from being disposed.
211
212 <p />These are the C equivalents of the <tt>System.GCHandle</tt>
213 structure.
214
215 <p />There are two kinds of GCHandles that can be created:
216
217 <ul>
218 <li>Handles to objects (use <tt><a href="#api:mono_gchandle_new">mono_gchandle_new</a></tt>).
219
220 <li>Weak handles to objects (use <tt><a href="#api:mono_gchandle_new_weakref">mono_gchandle_new_weakref</a></tt>).
221 Weak handles can have the objects reclaimed by the
222 garbage collector.
223
224 </li></li></ul>
225
226 <p />To retrieve the target address of an object pointed to by a
227 <tt>GCHandle</tt> you should use
228 <tt>mono_gchandle_get_target</tt>.
229
230 <p />For example, consider the following C code:
231
232 <div class="mapi-code">
233 static MonoObject* o = NULL;
234 </div>
235
236 <p />The object in `o' will *NOT* be scanned.
237
238 <p />If you need to store an object in a C variable and prevent
239 it from being collected, you need to acquire a GC handle for
240 it.
241
242 <div class="mapi-code">
243 guint32 handle = mono_gchandle_new (my_object, TRUE);
244 </div>
245
246 <p />TRUE means the object will be pinned, so it won't move in
247 memory when we'll use a moving GC. You can access the
248 MonoObject* referenced by a handle with:
249
250 <div class="mapi-code">
251 MonoObject* obj = mono_gchandle_get_target (handle);
252 </div>
253
254 <p />When you don't need the handle anymore you need to call:
255
256 <div class="mapi-code">
257 mono_gchandle_free (handle);
258 </div>
259
260 <p />Note that if you assign a new object to the C var, you need
261 to get a new handle, it's not enough to store a new object in
262 the C var.
263
264 <p />So code that looked like this:
265
266 <div class="mapi-code">
267 static MonoObject* obj = NULL;
268 ...
269 obj = mono_object_new (...);
270 // use obj
271 ...
272 // when done to allow the GC to collect obj
273 obj = NULL;
274 </div>
275
276 <p />should now be changed to:
277
278 <div class="mapi-code">
279 static guint32 o_handle;
280 ...
281 MonoObject *obj = mono_object_new (...);
282 o_handle = mono_gchandle_new (obj, TRUE);
283 // use o or mono_gchandle_get_target (o_handle)
284 ...
285 // when done to allow the GC to collect obj
286 mono_gchandle_free (o_handle);
287 </div>
288
289 <a name="api:mono_gchandle_new"></a>
290 <div class="mapi">
291 <div class="mapi-entry "><code>mono_gchandle_new</code></div>
292 <div class="mapi-height-container">
293 <div class="mapi-ptr-container"></div>
294 <div class="mapi-description">
295 <div class="mapi-ptr"></div>
296
297 <div class="mapi-declaration mapi-section">Syntax</div>
298 <div class="mapi-prototype">guint32
299 mono_gchandle_new_internal (MonoObject *obj, gboolean pinned)
300
301 </div>
302 <p />
303 <div class="mapi-section">Parameters</div>
304 <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>
305 <div> a handle that can be used to access the object from
306
307 unmanaged code.</div>
308 <div class="mapi-section">Description</div>
309 <div>
310 <p />
311 This returns a handle that wraps the object, this is used to keep a
312 reference to a managed object from the unmanaged world and preventing the
313 object from being disposed.
314 <p />
315 If <i>pinned</i> is false the address of the object can not be obtained, if it is
316 true the address of the object can be obtained. This will also pin the
317 object so it will not be possible by a moving garbage collector to move the
318 object.
319 <p /></div>
320 </div><!--mapi-description -->
321 </div><!--height container -->
322 </div> <!-- class=mapi -->
323
324 <a name="api:mono_gchandle_new_weakref"></a>
325 <div class="mapi">
326 <div class="mapi-entry "><code>mono_gchandle_new_weakref</code></div>
327 <div class="mapi-height-container">
328 <div class="mapi-ptr-container"></div>
329 <div class="mapi-description">
330 <div class="mapi-ptr"></div>
331
332 <div class="mapi-declaration mapi-section">Syntax</div>
333 <div class="mapi-prototype">uint32_t
334 mono_gchandle_new_weakref (MonoObject *obj, mono_bool track_resurrection)
335
336 </div>
337 <p />
338 <div class="mapi-section">Parameters</div>
339 <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>
340 <div> a handle that can be used to access the object from
341
342 unmanaged code.</div>
343 <div class="mapi-section">Description</div>
344 <div>
345 <p />
346 This returns a weak handle that wraps the object, this is used to
347 keep a reference to a managed object from the unmanaged world.
348 Unlike the <code>mono_gchandle_new_internal</code> the object can be reclaimed by the
349 garbage collector. In this case the value of the GCHandle will be
350 set to zero.
351 <p />
352 If <i>track_resurrection</i> is <code>TRUE</code> the object will be tracked through
353 finalization and if the object is resurrected during the execution
354 of the finalizer, then the returned weakref will continue to hold
355 a reference to the object. If <i>track_resurrection</i> is <code>FALSE</code>, then
356 the weak reference's target will become <code>NULL</code> as soon as the object
357 is passed on to the finalizer.
358 <p /></div>
359 </div><!--mapi-description -->
360 </div><!--height container -->
361 </div> <!-- class=mapi -->
362
363 <a name="api:mono_gchandle_get_target"></a>
364 <div class="mapi">
365 <div class="mapi-entry "><code>mono_gchandle_get_target</code></div>
366 <div class="mapi-height-container">
367 <div class="mapi-ptr-container"></div>
368 <div class="mapi-description">
369 <div class="mapi-ptr"></div>
370
371 <div class="mapi-declaration mapi-section">Syntax</div>
372 <div class="mapi-prototype">MonoObject*
373 mono_gchandle_get_target_internal (guint32 gchandle)
374
375 </div>
376 <p />
377 <div class="mapi-section">Parameters</div>
378 <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>
379 <div> A pointer to the <code>MonoObject*</code> represented by the handle or
380
381 <code>NULL</code> for a collected object if using a weakref handle.</div>
382 <div class="mapi-section">Description</div>
383 <div>
384 <p />
385 The handle was previously created by calling <code>mono_gchandle_new_internal</code> or
386 <code>mono_gchandle_new_weakref</code>.
387 <p /></div>
388 </div><!--mapi-description -->
389 </div><!--height container -->