X-Git-Url: http://wien.tomnetworks.com/gitweb/?a=blobdiff_plain;f=mono%2Fmetadata%2Fsgen-bridge.h;h=38dc44637cc05c1fea162908aec0bb741cfb0d8d;hb=08a728d237965feb2bbd485f909998b17c0bbb11;hp=8bfeb09a6d717af7a96f4ceeb1a03137c4e0519b;hpb=436328d91d590e68ccc87127920ba7cc6262fa0c;p=mono.git

diff --git a/mono/metadata/sgen-bridge.h b/mono/metadata/sgen-bridge.h
index 8bfeb09a6d7..38dc44637cc 100644
--- a/mono/metadata/sgen-bridge.h
+++ b/mono/metadata/sgen-bridge.h
@@ -1,24 +1,42 @@
 /*
  * 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.
+ */
+
+/*
+ * The bridge is a mechanism for SGen to let clients override the death of some
+ * 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
+ * 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.
+ *
+ * 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.
+ *
+ * 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
+ * the full, combined object graph is now instantiated on the Java side.  Then
+ * it triggers a Java GC, waits for it to finish, and checks which of the Java
+ * mirror objects are still alive.  For those it sets the `is_alive` flag and
+ * returns from the callback.
+ *
+ * The SCC analysis is done while the world is stopped, but the callback is made
+ * with the world running again.  Weak links to bridged objects and other
+ * objects reachable from them are kept until the callback returns, at which
+ * 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.
  */
 
 #ifndef _MONO_SGEN_BRIDGE_H_
@@ -56,14 +74,23 @@ typedef struct {
 
 typedef struct {
 	int bridge_version;
-	MonoGCBridgeObjectKind (*bridge_class_kind) (MonoClass *class);
+	/*
+	 * Tells the runtime which classes to even consider when looking for
+	 * bridged objects.  If subclasses are to be considered as well, the
+	 * subclass check must be done in the callback.
+	 */
+	MonoGCBridgeObjectKind (*bridge_class_kind) (MonoClass *klass);
+	/*
+	 * This is only called on objects for whose classes
+	 * `bridge_class_kind()` returned `XXX_BRIDGE_CLASS`.
+	 */
 	mono_bool (*is_bridge_object) (MonoObject *object);
 	void (*cross_references) (int num_sccs, MonoGCBridgeSCC **sccs, int num_xrefs, MonoGCBridgeXRef *xrefs);
 } MonoGCBridgeCallbacks;
 
-void mono_gc_register_bridge_callbacks (MonoGCBridgeCallbacks *callbacks);
+MONO_API void mono_gc_register_bridge_callbacks (MonoGCBridgeCallbacks *callbacks);
 
-void mono_gc_wait_for_bridge_processing (void);
+MONO_API void mono_gc_wait_for_bridge_processing (void);
 
 MONO_END_DECLS