docs/sources/mono-api-gchandle.html

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