| 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 |
<p>SGen is a concurrent and generational GC, features which require |
| 113 |
tracking changes to the state of the heap. This is achieved through |
| 114 |
write barriers. Whenever native code is changing the state of the |
| 115 |
heap by storing references into another managed object, it needs to |
| 116 |
do it using this write barrier API. |
| 117 |
|
| 118 |
<h4><a name="api:mono_gc_wbarrier_arrayref_copy">mono_gc_wbarrier_arrayref_copy</a></h4> |
| 119 |
<h4><a name="api:mono_gc_wbarrier_generic_nostore">mono_gc_wbarrier_generic_nostore</a></h4> |
| 120 |
<h4><a name="api:mono_gc_wbarrier_generic_store">mono_gc_wbarrier_generic_store</a></h4> |
| 121 |
<h4><a name="api:mono_gc_wbarrier_generic_store_atomic">mono_gc_wbarrier_generic_store_atomic</a></h4> |
| 122 |
<h4><a name="api:mono_gc_wbarrier_object_copy">mono_gc_wbarrier_object_copy</a></h4> |
| 123 |
<h4><a name="api:mono_gc_wbarrier_set_arrayref">mono_gc_wbarrier_set_arrayref</a></h4> |
| 124 |
<h4><a name="api:mono_gc_wbarrier_set_field">mono_gc_wbarrier_set_field</a></h4> |
| 125 |
<h4><a name="api:mono_gc_wbarrier_value_copy">mono_gc_wbarrier_value_copy</a></h4> |
| 126 |
|