diff --git a/doc/refcounting.txt b/doc/refcounting.txt
index 3cdb6058475fc9f5d63892e3c4900a29ac9f3fbd..e409262db7ca0f8d10d7242f2d4b924c28034cbd 100644 (file)
--- a/doc/refcounting.txt
+++ b/doc/refcounting.txt
examples are elements in a doubly-linked list with "prev" and "next"
pointers, and nodes in a tree, where a parent keeps a list of children, and
children keep a pointer to their parent. If both cases, if there is a "ref"
-in both directions, neither parent nor children can ever get freed.
+in both directions, neither object can ever get freed.
Because of this, circular data structures should be avoided when possible.
When they are necessary, try only "reffing" in one direction
ANCHORED OBJECTS
-The garbage collector cannot know about references from some types of objects:
+As a rule of thumb, the garbage collector can see pointers in:
- * Gtk/gtkmm widgets
+ * global/static variables in the program
- * SPObjects
+ * local variables/parameters
- * other GObject-derived types
+ * objects derived from GC::Managed<>
- * Glib data structures
+ * STL containers using GC::Alloc<>
- * STL data structures that don't use GC::Alloc
+ * objects manually allocated with GC::SCANNED
-To accomodate this, I've provided the GC::Anchored class from which
-garbage-collector managed classes can be derived if they need to be
-referenced from such places. As noted earlier, ref and unref functions are
-GC::anchor() and GC::release(), respectively.
+It cannot see pointers in:
+
+ * global/static variables in shared libraries
+
+ * objects not derived from GC::Managed<>
+
+ * STL containers not using GC::Alloc<>
+
+Since a lot of important objects (e.g. gtkmm widgets or Glib collections)
+fall into the latter category, I've provided the GC::Anchored class from
+which garbage-collector managed classes can be derived if they may be
+remembered in such places. As noted earlier, the associated ref and unref
+functions are GC::anchor() and GC::release(), respectively.
For most refcounted objects, a nonzero refcount means "this object is in
use", and a zero refcount means "this object is no longer in use, you can