[Python-Dev] Borrowed and Stolen References in API
marvin at rectangular.com
Tue May 10 02:58:35 CEST 2011
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
incremented: The caller has to account for an additional refcount.
decremented: The caller has to account for a lost refcount.
More information about the Python-Dev