[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