diff --git a/doc/refcounting.txt b/doc/refcounting.txt
index e3f6cf27fc5cf4c5adba6e4227a59d2b6b4b4a47..e409262db7ca0f8d10d7242f2d4b924c28034cbd 100644 (file)
--- a/doc/refcounting.txt
+++ b/doc/refcounting.txt
make the decision to unref it for them.
When you've unreffed the last ref you know about, you should generally
make the decision to unref it for them.
When you've unreffed the last ref you know about, you should generally
-assume that the object is now gone.
+assume that the object is now gone forever.
CIRCULAR REFERENCES
CIRCULAR REFERENCES
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"
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
Because of this, circular data structures should be avoided when possible.
When they are necessary, try only "reffing" in one direction
ANCHORED OBJECTS
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
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