docs/sources/mono-api-gc.html

   1 <h1>Garbage Collector Interface</h1>
   2
   3 <h1>Public Interface</h1>
   4
   5         <p>The public interface of the Mono GC is fairly limited, and
   6         its the only one that embedders should be using:
   7
   8 <h3>Garbage Collector</h3>
   9
  10 <h4><a name="api:mono_gc_collect">mono_gc_collect</a></h4>
  11 <h4><a name="api:mono_gc_collection_count">mono_gc_collection_count</a></h4>
  12 <h4><a name="api:mono_gc_max_generation">mono_gc_max_generation</a></h4>
  13 <h4><a name="api:mono_gc_get_generation">mono_gc_get_generation</a></h4>
  14 <h4><a name="api:mono_gc_get_heap_size">mono_gc_get_heap_size</a></h4>
  15 <h4><a name="api:mono_gc_get_used_size">mono_gc_get_used_size</a></h4>
  16 <h4><a name="api:mono_gc_walk_heap">mono_gc_walk_heap</a></h4>
  17
  18 <h3>Reference Queues</h3>
  19
  20 <h4><a name="api:mono_gc_reference_queue_add">mono_gc_reference_queue_add</a></h4>
  21 <h4><a name="api:mono_gc_reference_queue_free">mono_gc_reference_queue_free</a></h4>
  22 <h4><a name="api:mono_gc_reference_queue_new">mono_gc_reference_queue_new</a></h4>
  23
  24 <h3>SGen Bridge</h3>
  25
  26         <p>The bridge is a mechanism for SGen to let clients override
  27         the death of some unreachable objects.  We use it in monodroid
  28         to do garbage collection across the Mono and Java heaps.
  29
  30         <p>The client can designate some objects as "bridged", which
  31         means that they participate in the bridge processing step once
  32         SGen considers them unreachable, i.e., dead.  Bridged objects
  33         must be registered for finalization.
  34
  35         <p>When SGen is done marking, it puts together a list of all
  36         dead bridged objects and then does a strongly connected
  37         component analysis over their object graph.  That graph will
  38         usually contain non-bridged objects, too.
  39
  40         <p>The output of the SCC analysis is passed to the
  41         `cross_references()` callback.  It is expected to set the
  42         `is_alive` flag on those strongly connected components that it
  43         wishes to be kept alive.  The value of `is_alive` will be
  44         ignored on any SCCs which lack bridges.
  45
  46         <p>In monodroid each bridged object has a corresponding Java
  47         mirror object.  In the bridge callback it reifies the Mono
  48         object graph in the Java heap so that the full, combined
  49         object graph is now instantiated on the Java side.  Then it
  50         triggers a Java GC, waits for it to finish, and checks which
  51         of the Java mirror objects are still alive.  For those it sets
  52         the `is_alive` flag and returns from the callback.
  53
  54         <p>The SCC analysis is done while the world is stopped, but
  55         the callback is made with the world running again.  Weak links
  56         to bridged objects and other objects reachable from them are
  57         kept until the callback returns, at which point all links to
  58         bridged objects that don't have `is_alive` set are nulled.
  59         Note that weak links to non-bridged objects reachable from
  60         bridged objects are not nulled.  This might be considered a
  61         bug.
  62
  63 <div class="mapi-header">
  64 enum {
  65         SGEN_BRIDGE_VERSION = 5
  66 };
  67
  68 typedef enum {
  69         /* Instances of this class should be scanned when computing the transitive dependency among bridges. E.g. List of object*/
  70         GC_BRIDGE_TRANSPARENT_CLASS,
  71         /* Instances of this class should not be scanned when computing the transitive dependency among bridges. E.g. String*/
  72         GC_BRIDGE_OPAQUE_CLASS,
  73         /* Instances of this class should be bridged and have their dependency computed. */
  74         GC_BRIDGE_TRANSPARENT_BRIDGE_CLASS,
  75         /* Instances of this class should be bridged but no dependencies should not be calculated. */
  76         GC_BRIDGE_OPAQUE_BRIDGE_CLASS,
  77 } MonoGCBridgeObjectKind;
  78
  79 typedef struct {
  80         mono_bool is_alive;     /* to be set by the cross reference callback */
  81         int num_objs;
  82         MonoObject *objs [MONO_ZERO_LEN_ARRAY];
  83 } MonoGCBridgeSCC;
  84
  85 typedef struct {
  86         int src_scc_index;
  87         int dst_scc_index;
  88 } MonoGCBridgeXRef;
  89
  90 typedef struct {
  91         int bridge_version;
  92         /*
  93          * Tells the runtime which classes to even consider when looking for
  94          * bridged objects.  If subclasses are to be considered as well, the
  95          * subclass check must be done in the callback.
  96          */
  97         MonoGCBridgeObjectKind (*bridge_class_kind) (MonoClass *klass);
  98         /*
  99          * This is only called on objects for whose classes
 100          * `bridge_class_kind()` returned `XXX_BRIDGE_CLASS`.
 101          */
 102         mono_bool (*is_bridge_object) (MonoObject *object);
 103         void (*cross_references) (int num_sccs, MonoGCBridgeSCC **sccs, int num_xrefs, MonoGCBridgeXRef *xrefs);
 104 } MonoGCBridgeCallbacks;
 105 </div>
 106
 107 <h4><a name="api:mono_gc_register_bridge_callbacks">mono_gc_register_bridge_callbacks</a></h4>
 108 <h4><a name="api:mono_gc_wait_for_bridge_processing">mono_gc_wait_for_bridge_processing</a></h4>
 109
 110 <h3>Write Barriers</h3>
 111
 112 <h4><a name="api:mono_gc_wbarrier_arrayref_copy">mono_gc_wbarrier_arrayref_copy</a></h4>
 113 <h4><a name="api:mono_gc_wbarrier_generic_nostore">mono_gc_wbarrier_generic_nostore</a></h4>
 114 <h4><a name="api:mono_gc_wbarrier_generic_store">mono_gc_wbarrier_generic_store</a></h4>
 115 <h4><a name="api:mono_gc_wbarrier_generic_store_atomic">mono_gc_wbarrier_generic_store_atomic</a></h4>
 116 <h4><a name="api:mono_gc_wbarrier_object_copy">mono_gc_wbarrier_object_copy</a></h4>
 117 <h4><a name="api:mono_gc_wbarrier_set_arrayref">mono_gc_wbarrier_set_arrayref</a></h4>
 118 <h4><a name="api:mono_gc_wbarrier_set_field">mono_gc_wbarrier_set_field</a></h4>
 119 <h4><a name="api:mono_gc_wbarrier_value_copy">mono_gc_wbarrier_value_copy</a></h4>
 120