From cca66b9ec4e494c1d919bff0f71a820d8afab1fa Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 20:24:48 +0200 Subject: Adding upstream version 1.2.2. Signed-off-by: Daniel Baumann --- doc/refcounting.txt | 136 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 doc/refcounting.txt (limited to 'doc/refcounting.txt') diff --git a/doc/refcounting.txt b/doc/refcounting.txt new file mode 100644 index 0000000..e409262 --- /dev/null +++ b/doc/refcounting.txt @@ -0,0 +1,136 @@ +Refcounting +----------- + +INTRODUCTION + +Many objects in Inkscape have lifecycles which are managed by +"reference counting". Each such object has a counter associated with it, +which is supposed to reflect the number of outstanding references to it. +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 (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 +end up freeing the object out from under you). + +REFCOUNTING FUNCTIONS + +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), +and GC::anchor()/GC::release (for garbage-collector managed objects deriving +from GC::Anchored -- more on that later). + +[ 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 to your .cpp file + with: + + namespace GC = Inkscape::GC; + + Consider this encouragement to start writing new code in the Inkscape + namespace. ] + +REFCOUNTING POLICY + +Refcounted objects start with a reference count of one when they are +created. This means that you do not need to manually ref one that you've +just created. However, you will still be responsible for unreffing it when +you're done with it. + +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 (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 +is usually a recipe for confusion (and defeats the point of refcounting, +really). If you pass someone a pointer, they should be the ones responsible +for reffing it if they need to hold onto it. Similarly, you shouldn't try to +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 forever. + +CIRCULAR REFERENCES + +One disadvantage of reference counting is that a naive application of it +breaks down in the presence of objects that reference each other. Common +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 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 +(e.g. parent -> child) but not the other (e.g. child -> parent). + +This can sometimes be trickier than it sounds -- circular references don't +have to be direct to cause problems. A simple example of an indirect circular +reference would be a circular singly-linked list, where the "last" element +in the list points back to the "first". In that case, unidirectional +reffing isn't sufficient; you'd have no choice but to delegate ref handling to +some object which encapsuled the circular list, reffing and unreffing entries +as it added and removed them. + +ANCHORED OBJECTS + +As a rule of thumb, the garbage collector can see pointers in: + + * global/static variables in the program + + * local variables/parameters + + * objects derived from GC::Managed<> + + * STL containers using GC::Alloc<> + + * objects manually allocated with GC::SCANNED + +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 +free it now". For GC::Anchored objects, refcounting is merely an override +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 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 +GC::release the object immediately upon creating it. This is because the +garbage collector can see references to the object from parameters or local +variables. Trust the collector. + +One final note: when code is converted from pure refcounting to garbage +collection with GC::Anchored, refs and unrefs between GC::Anchored objects +should be removed. Refs are no longer necessary, and when circular references +are present, reffing will lead to memory leaks. + +Normally (unlike pure refcounting) the collector has no problem with freeing +circular references, but GC::anchor()ing a reference the collector can +already see overrides the collector's judgement. + -- cgit v1.2.3