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 an object's refcount
  25 (and perhaps make the final decision to free the object), but their names
  26 will vary 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 to your .cpp file
  36   with:
  37
  38     namespace GC = Inkscape::GC;
  39
  40   Consider this encouragement to start writing new code in the Inkscape
  41   namespace. ]
  42
  43 REFCOUNTING POLICY
  44
  45 Refcounted objects start with a reference count of one when they are
  46 created.  This means that you do not need to manually ref one that you've
  47 just created.  However, you will still be responsible for unreffing it when
  48 you're done with it.
  49
  50 This means that during the lifetime of an object, there should be N refs
  51 and N+1 unrefs on it.  If these become unbalanced, then you are likely to
  52 experience either transient crashing bugs (the object gets freed while
  53 someone is still using it) or memory leaks (the object never gets 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 forever.
  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 object 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 As a rule of thumb, the garbage collector can see pointers in:
  89
  90  * global/static variables in the program
  91
  92  * local variables/parameters
  93
  94  * objects derived from GC::Managed<>
  95
  96  * STL containers using GC::Alloc<>
  97
  98  * objects manually allocated with GC::SCANNED
  99
 100 It cannot see pointers in:
 101
 102  * global/static variables in shared libraries
 103
 104  * objects not derived from GC::Managed<>
 105
 106  * STL containers not using GC::Alloc<>
 107
 108 Since a lot of important objects (e.g. gtkmm widgets or Glib collections)
 109 fall into the latter category, I've provided the GC::Anchored class from
 110 which garbage-collector managed classes can be derived if they may be
 111 remembered in such places.  As noted earlier, the associated ref and unref
 112 functions are GC::anchor() and GC::release(), respectively.
 113
 114 For most refcounted objects, a nonzero refcount means "this object is in
 115 use", and a zero refcount means "this object is no longer in use, you can
 116 free it now".  For GC::Anchored objects, refcounting is merely an override
 117 to the normal operation of the garbage collector, so the rules are relaxed
 118 somewhat: a nonzero refcount merely means "the object is in use in places that
 119 the garbage collector can't see", and a zero refcount asserts that "the garbage
 120 collector can now see every use that matters".
 121
 122 While GC::Anchored objects start with an initial refcount of one like
 123 any other refcounted type, in most cases it's safe (and convenient) to
 124 GC::release the object immediately upon creating it.  This is because the
 125 garbage collector can see references to the object from parameters or local
 126 variables.  Trust the collector.
 127
 128 One final note:  when code is converted from pure refcounting to garbage
 129 collection with GC::Anchored, refs and unrefs between GC::Anchored objects
 130 should be removed.  Refs are no longer necessary, and when circular references
 131 are present, reffing will lead to memory leaks.
 132
 133 Normally (unlike pure refcounting) the collector has no problem with freeing
 134 circular references, but GC::anchor()ing a reference the collector can
 135 already see overrides the collector's judgement.
 136