[Python-Dev] Borrowed and Stolen References in API (original) (raw)

Marvin Humphrey 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 caller.

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

Marvin Humphrey

More information about the Python-Dev mailing list