Proposal: Ref Counting Conventions

[Michael Fleming <mfleming eazel com>]

Hi--

I'd like to propose the following conventions for reference-counting
Bonobo objects.  Reference counting is simple and effective, but it can
be tedious and error-prone.  The following conventions are inspired by
similar conventions adopted by COM users.

1. A function returning an object, either as the return value or
by-reference, must always add a reference before returning.  (example:
query_interface apparently does this)

2. If a function is passed an object as an in/out and wishes to return a
different object, the object that was passed in must be unref()'ed and
the new object ref()'d before returning

3. An object passed into a function needs only be ref()'d if the
function wishes to retain a reference do it beyond the scope of the
function call  (fairly obvious)

I'd like to suggest that these conventions be adopted by all
interfaces.  Users of interfaces should never have to ask "Do I need to
ref() this object that I got back from this function?"  or "Do I need to
unref this object before passing it into this function?"

In the Python/C API, some functions can "steal" references; that is,
they assume that they do not need to add a reference to objects passed
in as arguments. (see
http://www.python.org/doc/current/api/refcounts.html#SECTION003211000000000000000)
Although this idiom is probably useful for specific contexts, I'd like
to suggest that functions making use of Bonobo objects /never follow
this idiom/.  Similarly, some Python/C API functions return objects
without increasing their reference counts (eg list access functions).
I'd also like to suggest that this is a bad idea and that functions
returning Bonobo objects never do this.

Reference counting bugs are frustrating and hard to find., but if we
consistently follow the above conventions we may have fewer such bugs.

Mike Fleming
(Yes, I'm a new face)