[Python-Dev] Borrowed and Stolen References in API

[Marvin Humphrey]

On Tue, May 10, 2011 at 01:28:04PM +1200, Greg Ewing wrote:
> Marvin Humphrey wrote:
>
>>   incremented: The caller has to account for an additional refcount.
>>   decremented: The caller has to account for a lost refcount.
>
> I'm not sure that really clarifies anything. These terms
> sound like they're talking about the reference count of the
> object, but if they correspond to borrowed/stolen, they
> don't necessarily correlate with what actually happens to
> the reference count.

Hmm, they don't correspond to borrowed/stolen.

    stolen from the caller -> decremented
    stolen from the callee -> incremented
    borrowed               -> [no modifier]

We don't have a modifier keyword which is analogous to "borrowed".  The user
is expected to understand object lifespan issues for borrowed references
without explicit guidance.

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.
  * When a function accepts a "decremented" object as an argument, it will
    consume a refcount from it -- either right away, or at some point in the
    future.

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.

Cheers,

Marvin Humphrey