[Python-Dev] Borrowed and Stolen References in API

Nick Coghlan ncoghlan at gmail.com
Tue May 10 14:44:29 CEST 2011

On Tue, May 10, 2011 at 11:53 AM, Marvin Humphrey
<marvin at rectangular.com> wrote:
> With regards to "what actually happens to the reference count", I would argue
> that "incremented" and "decremented" are accurate descriptions.
>  * When a function returns an "incremented" object, that function has added
>    a refcount to it.

Except that's not quite true in cases like PySet_Pop(). In that case,
the net effect on the refcount is neutral. The significant point is
that the set no longer holds a reference, it has passed that
responsibility back to the caller.

> In my view, it is not desirable to label arguments or return values as
> "borrowed"; it is only necessary to advise the user when they must take action
> to account for a refcount, gained or lost.

Agreed on this part, though. Callers need to know when:

1. The return value is a new reference that must be decremented
(currently indicated in the docs by "Return value: New reference")
2. An input parameter transfers responsibility for the reference to
the callee (the only example I noticed in the docs is PyList_SetItem,
which uses an explicit note rather than any kind of markup or the
refcount data)

I believe the current refcount data covers the first case reasonably
well, but not the latter (and still has the problem of being separated
from the documentation of the functions themselves).


Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia

More information about the Python-Dev mailing list