Merge and cleanup of GSoC C++-ification project.

[inkscape.git] / doc / refcounting.txt

diff --git a/doc/refcounting.txt b/doc/refcounting.txt
index 3cdb6058475fc9f5d63892e3c4900a29ac9f3fbd..e409262db7ca0f8d10d7242f2d4b924c28034cbd 100644 (file)
--- a/doc/refcounting.txt
+++ b/doc/refcounting.txt
@@ -69,7 +69,7 @@ breaks down in the presence of objects that reference each other.  Common
 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
@@ -85,22 +85,31 @@ as it added and removed them.
 
 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