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