1 <h1>Garbage Collector Interface</h1>
3 <h1>Public Interface</h1>
5 <p>The public interface of the Mono GC is fairly limited, and
6 its the only one that embedders should be using:
8 <h3>Garbage Collector</h3>
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>
18 <h3>Reference Queues</h3>
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>
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.
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.
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.
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. Only bridged objects will be
44 reported to the callback, i.e., non-bridged objects are
45 removed from the callback graph.
47 <p>In monodroid each bridged object has a corresponding Java
48 mirror object. In the bridge callback it reifies the Mono
49 object graph in the Java heap so that the full, combined
50 object graph is now instantiated on the Java side. Then it
51 triggers a Java GC, waits for it to finish, and checks which
52 of the Java mirror objects are still alive. For those it sets
53 the `is_alive` flag and returns from the callback.
55 <p>The SCC analysis is done while the world is stopped, but
56 the callback is made with the world running again. Weak links
57 to bridged objects and other objects reachable from them are
58 kept until the callback returns, at which point all links to
59 bridged objects that don't have `is_alive` set are nulled.
60 Note that weak links to non-bridged objects reachable from
61 bridged objects are not nulled. This might be considered a
64 <div class="mapi-header">
66 SGEN_BRIDGE_VERSION = 4
70 /* Instances of this class should be scanned when computing the transitive dependency among bridges. E.g. List of object*/
71 GC_BRIDGE_TRANSPARENT_CLASS,
72 /* Instances of this class should not be scanned when computing the transitive dependency among bridges. E.g. String*/
73 GC_BRIDGE_OPAQUE_CLASS,
74 /* Instances of this class should be bridged and have their dependency computed. */
75 GC_BRIDGE_TRANSPARENT_BRIDGE_CLASS,
76 /* Instances of this class should be bridged but no dependencies should not be calculated. */
77 GC_BRIDGE_OPAQUE_BRIDGE_CLASS,
78 } MonoGCBridgeObjectKind;
81 mono_bool is_alive; /* to be set by the cross reference callback */
83 MonoObject *objs [MONO_ZERO_LEN_ARRAY];
94 * Tells the runtime which classes to even consider when looking for
95 * bridged objects. If subclasses are to be considered as well, the
96 * subclass check must be done in the callback.
98 MonoGCBridgeObjectKind (*bridge_class_kind) (MonoClass *klass);
100 * This is only called on objects for whose classes
101 * `bridge_class_kind()` returned `XXX_BRIDGE_CLASS`.
103 mono_bool (*is_bridge_object) (MonoObject *object);
104 void (*cross_references) (int num_sccs, MonoGCBridgeSCC **sccs, int num_xrefs, MonoGCBridgeXRef *xrefs);
105 } MonoGCBridgeCallbacks;
108 <h4><a name="api:mono_gc_register_bridge_callbacks">mono_gc_register_bridge_callbacks</a></h4>
109 <h4><a name="api:mono_gc_wait_for_bridge_processing">mono_gc_wait_for_bridge_processing</a></h4>
111 <h3>Write Barriers</h3>
113 <h4><a name="api:mono_gc_wbarrier_arrayref_copy">mono_gc_wbarrier_arrayref_copy</a></h4>
114 <h4><a name="api:mono_gc_wbarrier_generic_nostore">mono_gc_wbarrier_generic_nostore</a></h4>
115 <h4><a name="api:mono_gc_wbarrier_generic_store">mono_gc_wbarrier_generic_store</a></h4>
116 <h4><a name="api:mono_gc_wbarrier_generic_store_atomic">mono_gc_wbarrier_generic_store_atomic</a></h4>
117 <h4><a name="api:mono_gc_wbarrier_object_copy">mono_gc_wbarrier_object_copy</a></h4>
118 <h4><a name="api:mono_gc_wbarrier_set_arrayref">mono_gc_wbarrier_set_arrayref</a></h4>
119 <h4><a name="api:mono_gc_wbarrier_set_field">mono_gc_wbarrier_set_field</a></h4>
120 <h4><a name="api:mono_gc_wbarrier_value_copy">mono_gc_wbarrier_value_copy</a></h4>