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" <acon...@redhat.com> > To: proton@qpid.apache.org, "Rafael Schloming" <r...@alum.mit.edu> > Cc: "Andrew Stitcher" <astit...@redhat.com>, "Clifford Jansen" > <cjan...@redhat.com>, "Gordon Sim" <g...@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. > -- -- -- -K
