mono/metadata/sgen-bridge.h

   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