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
|
<h1>GC Handles</h1>
<h3>Synopsys</h3>
<div class="mapi-header">
@API_IDX@
</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.
</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>
<h4><a name="api:mono_gchandle_new">mono_gchandle_new</a></h4>
<h4><a name="api:mono_gchandle_new_weakref">mono_gchandle_new_weakref</a></h4>
<h4><a name="api:mono_gchandle_get_target">mono_gchandle_get_target</a></h4>
<h4><a name="api:mono_gchandle_free">mono_gchandle_free</a></h4>
|
