mono/metadata/sgen-bridge.h

   1 /*
   2  * Copyright 2011 Novell, Inc.
   3  *
   4  * Permission is hereby granted, free of charge, to any person obtaining
   5  * a copy of this software and associated documentation files (the
   6  * "Software"), to deal in the Software without restriction, including
   7  * without limitation the rights to use, copy, modify, merge, publish,
   8  * distribute, sublicense, and/or sell copies of the Software, and to
   9  * permit persons to whom the Software is furnished to do so, subject to
  10  * the following conditions:
  11  *
  12  * The above copyright notice and this permission notice shall be
  13  * included in all copies or substantial portions of the Software.
  14  *
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  17  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  18  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  19  * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  20  * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  21  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  22  */
  23
  24 /*
  25  * The bridge is a mechanism for SGen to let clients override the death of some
  26  * unreachable objects.  We use it in monodroid to do garbage collection across
  27  * the Mono and Java heaps.
  28  *
  29  * The client can designate some objects as "bridged", which means that they
  30  * participate in the bridge processing step once SGen considers them
  31  * unreachable, i.e., dead.  Bridged objects must be registered for
  32  * finalization.
  33  *
  34  * When SGen is done marking, it puts together a list of all dead bridged
  35  * objects and then does a strongly connected component analysis over their
  36  * object graph.  That graph will usually contain non-bridged objects, too.
  37  *
  38  * The output of the SCC analysis is passed to the `cross_references()`
  39  * callback.  It is expected to set the `is_alive` flag on those strongly
  40  * connected components that it wishes to be kept alive.  Only bridged objects
  41  * will be reported to the callback, i.e., non-bridged objects are removed from
  42  * the callback graph.
  43  *
  44  * In monodroid each bridged object has a corresponding Java mirror object.  In
  45  * the bridge callback it reifies the Mono object graph in the Java heap so that
  46  * the full, combined object graph is now instantiated on the Java side.  Then
  47  * it triggers a Java GC, waits for it to finish, and checks which of the Java
  48  * mirror objects are still alive.  For those it sets the `is_alive` flag and
  49  * returns from the callback.
  50  *
  51  * The SCC analysis is done while the world is stopped, but the callback is made
  52  * with the world running again.  Weak links to bridged objects and other
  53  * objects reachable from them are kept until the callback returns, at which
  54  * point all links to bridged objects that don't have `is_alive` set are nulled.
  55  * Note that weak links to non-bridged objects reachable from bridged objects
  56  * are not nulled.  This might be considered a bug.
  57  */
  58
  59 #ifndef _MONO_SGEN_BRIDGE_H_
  60 #define _MONO_SGEN_BRIDGE_H_
  61
  62 #include <mono/utils/mono-publib.h>
  63
  64 MONO_BEGIN_DECLS
  65
  66 enum {
  67         SGEN_BRIDGE_VERSION = 4
  68 };
  69
  70 typedef enum {
  71         /* Instances of this class should be scanned when computing the transitive dependency among bridges. E.g. List<object>*/
  72         GC_BRIDGE_TRANSPARENT_CLASS,
  73         /* Instances of this class should not be scanned when computing the transitive dependency among bridges. E.g. String*/
  74         GC_BRIDGE_OPAQUE_CLASS,
  75         /* Instances of this class should be bridged and have their dependency computed. */
  76         GC_BRIDGE_TRANSPARENT_BRIDGE_CLASS,
  77         /* Instances of this class should be bridged but no dependencies should not be calculated. */
  78         GC_BRIDGE_OPAQUE_BRIDGE_CLASS,
  79 } MonoGCBridgeObjectKind;
  80
  81 typedef struct {
  82         mono_bool is_alive;     /* to be set by the cross reference callback */
  83         int num_objs;
  84         MonoObject *objs [MONO_ZERO_LEN_ARRAY];
  85 } MonoGCBridgeSCC;
  86
  87 typedef struct {
  88         int src_scc_index;
  89         int dst_scc_index;
  90 } MonoGCBridgeXRef;
  91
  92 typedef struct {
  93         int bridge_version;
  94         /*
  95          * Tells the runtime which classes to even consider when looking for
  96          * bridged objects.  If subclasses are to be considered as well, the
  97          * subclass check must be done in the callback.
  98          */
  99         MonoGCBridgeObjectKind (*bridge_class_kind) (MonoClass *klass);
 100         /*
 101          * This is only called on objects for whose classes
 102          * `bridge_class_kind()` returned `XXX_BRIDGE_CLASS`.
 103          */
 104         mono_bool (*is_bridge_object) (MonoObject *object);
 105         void (*cross_references) (int num_sccs, MonoGCBridgeSCC **sccs, int num_xrefs, MonoGCBridgeXRef *xrefs);
 106 } MonoGCBridgeCallbacks;
 107
 108 MONO_API void mono_gc_register_bridge_callbacks (MonoGCBridgeCallbacks *callbacks);
 109
 110 MONO_API void mono_gc_wait_for_bridge_processing (void);
 111
 112 MONO_END_DECLS
 113
 114 #endif