Re: [Python-Dev] Borrowed and Stolen References in API

[Marvin Humphrey]

On Tue, May 10, 2011 at 12:13:47PM +1200, Greg Ewing wrote:
> Nick Coghlan wrote:
>
>> One interesting aspect is that from the caller's point of view, a
>> *new* reference to the relevant behaves like a borrowed reference for
>> input parameters, but like a stolen reference for output parameters
>> and return values.
>
> I think it's less confusing to use the term "new" only for
> output/return values, and "stolen" only for input values.
>
> Inputs are either "borrowed" or "stolen" (by the callee).
>
> Outputs are either "new" (to the caller) or "borrowed"
> (by the caller).
>
> (Or maybe the terms for outputs should be "given" and "lent"?-)

To solve this problem in a similar system (the Clownfish object system used by
Apache Lucy) we used the keywords "incremented" and "decremented".  Applied to
some Python C API function documentation:

  incremented PyObject* PyTuple_New(Py_ssize_t len)

  int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, 
  decremented PyObject *o)

With "incremented" and "decremented", the perspective is always that of the
caller.  

  incremented: The caller has to account for an additional refcount.
  decremented: The caller has to account for a lost refcount.

Marvin Humphrey

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [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

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com