doc/refcounting.txt

   1 Refcounting
   2 -----------
   3
   4 INTRODUCTION
   5
   6 Many objects in Inkscape have lifecycles which are managed by
   7 "reference counting".  Each such object has a counter associated with it,
   8 which is supposed to reflect the number of outstanding references to it.
   9 When that counter falls to zero, the object can be freed.
  10
  11 This releases the programmer from worrying about having freed an object
  12 while somebody else is still using it (or someone else freeing while
  13 you're using it!).  Simply "ref" the object (increment the counter) to
  14 stake your claim, and then "unref" it (decrement the counter) when you don't
  15 need it anymore.  The ultimate decision to free the object is made safely
  16 behind the scenes.
  17
  18 You should "ref" an object whenever you plan to hold onto it while
  19 transferring control to another part of the code (which might otherwise
  20 end up freeing the object out from under you).
  21
  22 REFCOUNTING FUNCTIONS
  23
  24 Ref and unref functions are provided to manipulate object counter (and make
  25 the final decision to free the object for you), but their names will vary
  26 depending on the type of object.
  27
  28 Examples include g_object_ref()/g_object_unref() (for most GObject-based
  29 types), sp_object_ref()/sp_object_unref() (for SPObject-derived classes),
  30 and GC::anchor()/GC::release (for garbage-collector managed objects deriving
  31 from GC::Anchored -- more on that later).
  32
  33 [ note: for code underneath the Inkscape namespace, you need only write
  34   GC::anchor(), but in other code you will need to write
  35   Inkscape::GC::anchor(), or import the GC namespace with:
  36
  37     namespace GC = Inkscape::GC;
  38
  39   Consider this encouragement to start writing new code in the Inkscape
  40   namespace. ]
  41
  42 REFCOUNTING POLICY
  43
  44 Refcounted objects start with a reference count of one when they are
  45 created.  This means that you do not need to manually ref one that you've
  46 just created.  However, you will still be responsible for unreffing it when
  47 you're done with it.
  48
  49 This means that during the lifetime of an object, there should be N refs
  50 and N+1 unrefs on it.  If these become unbalanced, then you are likely to
  51 experience either transient crashing bugs (since the object could get freed
  52 while someone is still using it) or memory leaks (the object is forgotten
  53 while it still has a nonzero refcount, so it is never freed).
  54
  55 As a rule, an object should be unreffed by the same class or compilation
  56 unit that reffed it.  Reffing or unreffing an object on someone else's behalf
  57 is usually a recipe for confusion (and defeats the point of refcounting,
  58 really).  If you pass someone a pointer, they should be the ones responsible
  59 for reffing it if they need to hold onto it.  Similarly, you shouldn't try to
  60 make the decision to unref it for them.
  61
  62 When you've unreffed the last ref you know about, you should generally
  63 assume that the object is now gone.
  64
  65 CIRCULAR REFERENCES
  66
  67 One disadvantage of reference counting is that a naive application of it
  68 breaks down in the presence of objects that reference each other.  Common
  69 examples are elements in a doubly-linked list with "prev" and "next"
  70 pointers, and nodes in a tree, where a parent keeps a list of children, and
  71 children keep a pointer to their parent.  If both cases, if there is a "ref"
  72 in both directions, neither parent nor children can ever get freed.
  73
  74 Because of this, circular data structures should be avoided when possible.
  75 When they are necessary, try only "reffing" in one direction
  76 (e.g. parent -> child) but not the other (e.g. child -> parent).
  77
  78 This can sometimes be trickier than it sounds -- circular references don't
  79 have to be direct to cause problems.  A simple example of an indirect circular
  80 reference would be a circular singly-linked list, where the "last" element
  81 in the list points back to the "first".  In that case, unidirectional
  82 reffing isn't sufficient; you'd have no choice but to delegate ref handling to
  83 some object which encapsuled the circular list, reffing and unreffing entries
  84 as it added and removed them.
  85
  86 ANCHORED OBJECTS
  87
  88 The garbage collector cannot know about references from some types of objects:
  89
  90  * Gtk/gtkmm widgets
  91
  92  * SPObjects
  93
  94  * other GObject-derived types
  95
  96  * Glib data structures
  97
  98  * STL data structures that don't use GC::Alloc
  99
 100 To accomodate this, I've provided the GC::Anchored class from which
 101 garbage-collector managed classes can be derived if they need to be
 102 referenced from such places.  As noted earlier, ref and unref functions are
 103 GC::anchor() and GC::release(), respectively.
 104
 105 For most refcounted objects, a nonzero refcount means "this object is in
 106 use", and a zero refcount means "this object is no longer in use, you can
 107 free it now".  For GC::Anchored objects, refcounting is merely an override
 108 to the normal operation of the garbage collector, so the rules are relaxed
 109 somewhat: a nonzero refcount merely means "the object is in use in places that
 110 the garbage collector can't see", and a zero refcount asserts that "the garbage
 111 collector can see every use that matters".
 112
 113 While GC::Anchored objects start with an initial refcount of one like
 114 any other refcounted type, in most cases it's safe (and convenient) to
 115 GC::release the object immediately upon creating it.  This is because the
 116 garbage collector can see references to the object from parameters or local
 117 variables.  Trust the collector.
 118
 119 One final note:  when code is converted from pure refcounting to garbage
 120 collection with GC::Anchored, refs and unrefs between GC::Anchored objects
 121 should be removed.  Refs are no longer necessary, and when circular references
 122 are present, reffing will lead to memory leaks.
 123
 124 Normally (unlike pure refcounting) the collector has no problem with freeing
 125 circular references, but GC::anchor()ing a reference the collector can
 126 already see overrides the collector's judgement.
 127