Merge pull request #5714 from alexischr/update_bockbuild

[mono.git] / mono / metadata / sgen-bridge.h

diff --git a/mono/metadata/sgen-bridge.h b/mono/metadata/sgen-bridge.h
index 28bf2caf759969be762332c9d9cc4eea504022fd..c131f3066914e0c334f3a7bbb7f947f307bd1aca 100644 (file)
--- a/mono/metadata/sgen-bridge.h
+++ b/mono/metadata/sgen-bridge.h
@@ -1,24 +1,8 @@
-/*
+/**
+ * \file
  * Copyright 2011 Novell, Inc.
  * 
- * Permission is hereby granted, free of charge, to any person obtaining
- * a copy of this software and associated documentation files (the
- * "Software"), to deal in the Software without restriction, including
- * without limitation the rights to use, copy, modify, merge, publish,
- * distribute, sublicense, and/or sell copies of the Software, and to
- * permit persons to whom the Software is furnished to do so, subject to
- * the following conditions:
- * 
- * The above copyright notice and this permission notice shall be
- * included in all copies or substantial portions of the Software.
- * 
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
- * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
- * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
- * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
- * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
- * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
- * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ * Licensed under the MIT license. See LICENSE file in the project root for full license information.
  */
 
 /*
@@ -26,20 +10,23 @@
  * unreachable objects.  We use it in monodroid to do garbage collection across
  * the Mono and Java heaps.
  *
- * The client can designate some objects as "bridged", which means that they
- * participate in the bridge processing step once SGen considers them
+ * The client (Monodroid) can designate some objects as "bridged", which means
+ * that they participate in the bridge processing step once SGen considers them
  * unreachable, i.e., dead.  Bridged objects must be registered for
  * finalization.
  *
  * When SGen is done marking, it puts together a list of all dead bridged
- * objects and then does a strongly connected component analysis over their
- * object graph.  That graph will usually contain non-bridged objects, too.
+ * objects.  This is passed to the bridge processor, which does an analysis to
+ * simplify the graph: It replaces strongly-connected components with single
+ * nodes, and may remove nodes corresponding to components which do not contain
+ * bridged objects.
  *
- * The output of the SCC analysis is passed to the `cross_references()`
- * callback.  It is expected to set the `is_alive` flag on those strongly
- * connected components that it wishes to be kept alive.  Only bridged objects
- * will be reported to the callback, i.e., non-bridged objects are removed from
- * the callback graph.
+ * The output of the SCC analysis is passed to the client's `cross_references()`
+ * callback.  This consists of 2 arrays, an array of SCCs (MonoGCBridgeSCC),
+ * and an array of "xrefs" (edges between SCCs, MonoGCBridgeXRef).  Edges are
+ * encoded as pairs of "API indices", ie indexes in the SCC array.  The client
+ * is expected to set the `is_alive` flag on those strongly connected components
+ * that it wishes to be kept alive.
  *
  * In monodroid each bridged object has a corresponding Java mirror object.  In
  * the bridge callback it reifies the Mono object graph in the Java heap so that
@@ -54,6 +41,10 @@
  * point all links to bridged objects that don't have `is_alive` set are nulled.
  * Note that weak links to non-bridged objects reachable from bridged objects
  * are not nulled.  This might be considered a bug.
+ *
+ * There are three different implementations of the bridge processor, each of
+ * which implements 8 callbacks (see SgenBridgeProcessor).  The implementations
+ * differ in the algorithm they use to compute the "simplified" SCC graph.
  */
 
 #ifndef _MONO_SGEN_BRIDGE_H_
@@ -64,7 +55,7 @@
 MONO_BEGIN_DECLS
 
 enum {
-       SGEN_BRIDGE_VERSION = 4
+       SGEN_BRIDGE_VERSION = 5
 };
        
 typedef enum {
@@ -105,6 +96,11 @@ typedef struct {
        void (*cross_references) (int num_sccs, MonoGCBridgeSCC **sccs, int num_xrefs, MonoGCBridgeXRef *xrefs);
 } MonoGCBridgeCallbacks;
 
+/*
+ * Note: This may be called at any time, but cannot be called concurrently
+ * with (during and on a separate thread from) sgen init. Callers are
+ * responsible for enforcing this.
+ */
 MONO_API void mono_gc_register_bridge_callbacks (MonoGCBridgeCallbacks *callbacks);
 
 MONO_API void mono_gc_wait_for_bridge_processing (void);