qpid-proton mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ken Giusti <kgiu...@redhat.com>
Subject Re: All about proton memory management (or C++, python and Go - Oh My!)
Date Wed, 19 Aug 2015 14:45:20 GMT
Nicely done Alan! 

One point - I'm a little confused about your advice regarding pn_object_decref: 

> The proton C API has standard reference counting rules (but see [1] below)

> * A pointer returned by a pn_ function is either borrowed by the caller, or
> the caller owns a reference (the API doc says which.)
> * The owner of a reference must call pn_object_decref() exactly once to
> release it.

Really?  What about those proton objects that have a pn_X_free() method?  I believe the corresponding
pn_X() allocation methods pass back an owning reference to the object.  If a pn_X_free() exists
(and the user never calls pn_object_incref() on the object), shouldn't the user use the pn_X_free()
method instead?

Maybe the doc should make that distinction, e.g.:

* if an object of type pn_X_t has a corresponding pn_X_free() method, call the pn_X_free()
method to release your reference to the object.
* otherwise, if you have called pn_object_incref() on the object, you must call pn_object_decref()
on the object to release your reference.

> * To keep a borrowed pointer, call pn_object_incref() . This adds a new
> reference, which you now own.
> * A pointer passed to a pn_ function has no change of ownership. If you owned
> a reference you still do, if you didn't you still don't.
> * An object is never freed while there are still references to it.
> * An object is freed when all references to it are released.

----- Original Message ----- 

> From: "aconway" <aconway@redhat.com>
> To: proton@qpid.apache.org, "Rafael Schloming" <rhs@alum.mit.edu>
> Cc: "Andrew Stitcher" <astitche@redhat.com>, "Clifford Jansen"
> <cjansen@redhat.com>, "Gordon Sim" <gsim@redhat.com>
> Sent: Tuesday, August 18, 2015 3:50:35 PM
> Subject: Re: All about proton memory management (or C++, python and Go - Oh
> My!)

> On Tue, 2015-08-18 at 12:09 -0400, Andrew Stitcher wrote:
> > On Tue, 2015-08-18 at 07:38 -0400, Rafael Schloming wrote:
> > > Nice writeup!
> >
> > I agree.
> >
> > Andrew
> >
> > [Did you make a pass through the doc to ensure that the claimed API
> > doc
> > is actually there? that is, doc on ownership and scope?]
> >

> No, will add to my TODO list :) Some of it definitely is but I don't
> know if is uniform and complete. The existing doc does not refer to
> refcounts, it talks of pointers "becoming invalid". I think that is the
> correct language - we don't want to give the impression that refcounts
> are mandatory. The discussion of refcounting can clarify that "becomes
> invalid" means the implied _reference_ becomes invalid. The actual
> object might not be freed immediately (with or without user refcounts
> because of containment) but in any case it is no longer your business.
> You must treat that pointer or the implied reference as invalid or you
> are deep in "works in tests, core dumps in production" territory.

> Thanks for the feedback!
> Alan.

> --


View raw message