Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
-----------
INTRODUCTION
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
[ 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;
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).
When you've unreffed the last ref you know about, you should generally
assume that the object is now gone forever.
CIRCULAR REFERENCES
ANCHORED OBJECTS
* local variables/parameters
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.