![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/refcounting.txt b/doc/refcounting.txt
index b6a7bf433e195015df0882299eaebedcc88516cf..e409262db7ca0f8d10d7242f2d4b924c28034cbd 100644 (file)
--- a/doc/refcounting.txt
+++ b/doc/refcounting.txt
When that counter falls to zero, the object can be freed.
This releases the programmer from worrying about having freed an object
-while somebody else is still using it. Simply "ref" the object (increment
-the counter) when you first hold onto it, and "unref" it (decrement the
-counter) when you don't need it anymore. The ultimate decision to free
-the object is made for you behind the scenes.
+while somebody else is still using it (or someone else freeing while
+you're using it!). Simply "ref" the object (increment the counter) to
+stake your claim, and then "unref" it (decrement the counter) when you don't
+need it anymore. The ultimate decision to free the object is made safely
+behind the scenes.
You should "ref" an object whenever you plan to hold onto it while
transferring control to another part of the code (which might otherwise
REFCOUNTING FUNCTIONS
-Ref and unref functions are provided to manipulate object counter (and make
-the final decision to free the object for you), but their names will vary
-depending on the type of object.
+Ref and unref functions are provided to manipulate an object's refcount
+(and perhaps make the final decision to free the object), but their names
+will vary depending on the type of object.
Examples include g_object_ref()/g_object_unref() (for most GObject-based
types), sp_object_ref()/sp_object_unref() (for SPObject-derived classes),
[ note: for code underneath the Inkscape namespace, you need only write
GC::anchor(), but in other code you will need to write
- Inkscape::GC::anchor(), or import the GC namespace with:
+ Inkscape::GC::anchor(), or import the GC namespace to your .cpp file
+ with:
namespace GC = Inkscape::GC;
This means that during the lifetime of an object, there should be N refs
and N+1 unrefs on it. If these become unbalanced, then you are likely to
-experience either transient crashing bugs (since the object could get freed
-while someone is still using it) or memory leaks (the object is forgotten
-while it still has a nonzero refcount, so it is never freed).
+experience either transient crashing bugs (the object gets freed while
+someone is still using it) or memory leaks (the object never gets freed).
As a rule, an object should be unreffed by the same class or compilation
unit that reffed it. Reffing or unreffing an object on someone else's behalf
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
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
to the normal operation of the garbage collector, so the rules are relaxed
somewhat: a nonzero refcount merely means "the object is in use in places that
the garbage collector can't see", and a zero refcount asserts that "the garbage
-collector can see every use that matters".
+collector can now see every use that matters".
While GC::Anchored objects start with an initial refcount of one like
any other refcounted type, in most cases it's safe (and convenient) to