mono/docscripts/sources/mono-api-gchandle.html

   1 <h1>GC Hnadles</h1>
   2
   3         <p>GC handles are wrappers that are used to keep references to
   4         managed objects in the unmanaged space and preventing the
   5         object from being disposed.
   6
   7         <p>These are the C equivalents of the <tt>System.GCHandle</tt>
   8         structure.
   9
  10         <p>There are two kinds of GCHandles that can be created:
  11
  12         <ul>
  13                 <li>Handles to objects (use <tt><a
  14                 href="api:mono_gchandle_new">mono_gchandle_new</a></tt>).
  15
  16                 <li>Weak handles to objects (use <tt><a
  17                 href="api:mono_gchandle_new_weakref">mono_gchandle_new_weakref</a></tt>).
  18                 Weak handles can have the objects reclaimed by the
  19                 garbage collector.
  20
  21         </ul>
  22
  23         <p>To retrieve the target address of an object pointed to by a
  24         <tt>GCHandle</tt> you should use
  25         <tt>mono_gchandle_get_target</tt>.
  26
  27         <p>For example, consider the following C code:
  28 <pre>
  29 static MonoObject* o = NULL;
  30 </pre>
  31
  32         <p>The object in `o' will *NOT* be scanned.
  33
  34         <p>If you need to store an object in a C variable and prevent
  35         it from being collected, you need to acquire a GC handle for
  36         it.
  37
  38 <pre>
  39         guint32 handle = mono_gchandle_new (my_object, TRUE);
  40 </pre>
  41
  42         <p>TRUE means the object will be pinned, so it won't move in
  43         memory when we'll use a moving GC. You can access the
  44         MonoObject* referenced by a handle with:
  45
  46 <pre>
  47         MonoObject* obj = mono_gchandle_get_target (handle);
  48 </pre>
  49
  50         <p>When you don't need the handle anymore you need to call:
  51
  52 <pre>
  53         mono_gchandle_free (handle);
  54 </pre>
  55
  56         <p>Note that if you assign a new object to the C var, you need
  57         to get a new handle, it's not enough to store a new object in
  58         the C var.
  59
  60         <p>So code that looked like this:
  61
  62 <pre>
  63         static MonoObject* o = NULL;
  64         ...
  65         o = mono_object_new (...);
  66         /* use o */
  67         ...
  68         /* when done to allow the GC to collect o */
  69         o = NULL;
  70 </pre>
  71
  72         <p>should now be changed to:
  73
  74 <pre>
  75         static guint32 o_handle;
  76         ...
  77         MonoObject *o = mono_object_new (...);
  78         o_handle = mono_gchandle_new (o, TRUE);
  79         /* use o or mono_gchandle_get_target (o_handle) */
  80         ...
  81         /* when done to allow the GC to collect o */
  82         mono_gchandle_free (o_handle);
  83 </pre>
  84
  85 <h4><a name="api:mono_gchandle_new">mono_gchandle_new</a></h4>
  86 <h4><a name="api:mono_gchandle_new_weakref">mono_gchandle_new_weakref</a></h4>
  87 <h4><a name="api:mono_gchandle_get_target">mono_gchandle_get_target</a></h4>
  88 <h4><a name="api:mono_gchandle_is_in_domain">mono_gchandle_is_in_domain</a></h4>
  89 <h4><a name="api:mono_gchandle_free">mono_gchandle_free</a></h4>