1 /** 2 * \file 3 * Copyright 2011 Novell, Inc. 4 * 5 * Licensed under the MIT license. See LICENSE file in the project root for full license information. 6 */ 7 8 /* 9 * The bridge is a mechanism for SGen to let clients override the death of some 10 * unreachable objects. We use it in monodroid to do garbage collection across 11 * the Mono and Java heaps. 12 * 13 * The client (Monodroid) can designate some objects as "bridged", which means 14 * that they participate in the bridge processing step once SGen considers them 15 * unreachable, i.e., dead. Bridged objects must be registered for 16 * finalization. 17 * 18 * When SGen is done marking, it puts together a list of all dead bridged 19 * objects. This is passed to the bridge processor, which does an analysis to 20 * simplify the graph: It replaces strongly-connected components with single 21 * nodes, and may remove nodes corresponding to components which do not contain 22 * bridged objects. 23 * 24 * The output of the SCC analysis is passed to the client's `cross_references()` 25 * callback. This consists of 2 arrays, an array of SCCs (MonoGCBridgeSCC), 26 * and an array of "xrefs" (edges between SCCs, MonoGCBridgeXRef). Edges are 27 * encoded as pairs of "API indices", ie indexes in the SCC array. The client 28 * is expected to set the `is_alive` flag on those strongly connected components 29 * that it wishes to be kept alive. 30 * 31 * In monodroid each bridged object has a corresponding Java mirror object. In 32 * the bridge callback it reifies the Mono object graph in the Java heap so that 33 * the full, combined object graph is now instantiated on the Java side. Then 34 * it triggers a Java GC, waits for it to finish, and checks which of the Java 35 * mirror objects are still alive. For those it sets the `is_alive` flag and 36 * returns from the callback. 37 * 38 * The SCC analysis is done while the world is stopped, but the callback is made 39 * with the world running again. Weak links to bridged objects and other 40 * objects reachable from them are kept until the callback returns, at which 41 * point all links to bridged objects that don't have `is_alive` set are nulled. 42 * Note that weak links to non-bridged objects reachable from bridged objects 43 * are not nulled. This might be considered a bug. 44 * 45 * There are three different implementations of the bridge processor, each of 46 * which implements 8 callbacks (see SgenBridgeProcessor). The implementations 47 * differ in the algorithm they use to compute the "simplified" SCC graph. 48 */ 49 50 #ifndef _MONO_SGEN_BRIDGE_H_ 51 #define _MONO_SGEN_BRIDGE_H_ 52 53 #include <mono/utils/mono-publib.h> 54 55 MONO_BEGIN_DECLS 56 57 enum { 58 SGEN_BRIDGE_VERSION = 5 59 }; 60 61 typedef enum { 62 /* Instances of this class should be scanned when computing the transitive dependency among bridges. E.g. List<object>*/ 63 GC_BRIDGE_TRANSPARENT_CLASS, 64 /* Instances of this class should not be scanned when computing the transitive dependency among bridges. E.g. String*/ 65 GC_BRIDGE_OPAQUE_CLASS, 66 /* Instances of this class should be bridged and have their dependency computed. */ 67 GC_BRIDGE_TRANSPARENT_BRIDGE_CLASS, 68 /* Instances of this class should be bridged but no dependencies should not be calculated. */ 69 GC_BRIDGE_OPAQUE_BRIDGE_CLASS, 70 } MonoGCBridgeObjectKind; 71 72 typedef struct { 73 mono_bool is_alive; /* to be set by the cross reference callback */ 74 int num_objs; 75 MonoObject *objs [MONO_ZERO_LEN_ARRAY]; 76 } MonoGCBridgeSCC; 77 78 typedef struct { 79 int src_scc_index; 80 int dst_scc_index; 81 } MonoGCBridgeXRef; 82 83 typedef struct { 84 int bridge_version; 85 /* 86 * Tells the runtime which classes to even consider when looking for 87 * bridged objects. If subclasses are to be considered as well, the 88 * subclass check must be done in the callback. 89 */ 90 MonoGCBridgeObjectKind (*bridge_class_kind) (MonoClass *klass); 91 /* 92 * This is only called on objects for whose classes 93 * `bridge_class_kind()` returned `XXX_BRIDGE_CLASS`. 94 */ 95 mono_bool (*is_bridge_object) (MonoObject *object); 96 void (*cross_references) (int num_sccs, MonoGCBridgeSCC **sccs, int num_xrefs, MonoGCBridgeXRef *xrefs); 97 } MonoGCBridgeCallbacks; 98 99 /* 100 * Note: This may be called at any time, but cannot be called concurrently 101 * with (during and on a separate thread from) sgen init. Callers are 102 * responsible for enforcing this. 103 */ 104 MONO_API void mono_gc_register_bridge_callbacks (MonoGCBridgeCallbacks *callbacks); 105 106 MONO_API void mono_gc_wait_for_bridge_processing (void); 107 108 MONO_END_DECLS 109 110 #endif 111