|
|
|
Extending and Embedding the Python Interpreter |
|
|
|
1.10.2 Ownership Rules
Whenever an object reference is passed into or out of a function, it
is part of the function's interface specification whether ownership is
transferred with the reference or not.
Most functions that return a reference to an object pass on ownership
with the reference. In particular, all functions whose function it is
to create a new object, such as PyInt_FromLong() and
Py_BuildValue(), pass ownership to the receiver. Even if
the object is not actually new, you still receive ownership of a new
reference to that object. For instance, PyInt_FromLong()
maintains a cache of popular values and can return a reference to a
cached item.
Many functions that extract objects from other objects also transfer
ownership with the reference, for instance
PyObject_GetAttrString(). The picture is less clear, here,
however, since a few common routines are exceptions:
PyTuple_GetItem(), PyList_GetItem(),
PyDict_GetItem(), and PyDict_GetItemString()
all return references that you borrow from the tuple, list or
dictionary.
The function PyImport_AddModule() also returns a borrowed
reference, even though it may actually create the object it returns:
this is possible because an owned reference to the object is stored in
sys.modules .
When you pass an object reference into another function, in general,
the function borrows the reference from you -- if it needs to store
it, it will use Py_INCREF() to become an independent
owner. There are exactly two important exceptions to this rule:
PyTuple_SetItem() and PyList_SetItem(). These
functions take over ownership of the item passed to them -- even if
they fail! (Note that PyDict_SetItem() and friends don't
take over ownership -- they are ``normal.'')
When a C function is called from Python, it borrows references to its
arguments from the caller. The caller owns a reference to the object,
so the borrowed reference's lifetime is guaranteed until the function
returns. Only when such a borrowed reference must be stored or passed
on, it must be turned into an owned reference by calling
Py_INCREF().
The object reference returned from a C function that is called from
Python must be an owned reference -- ownership is transferred from
the function to its caller.
Release 2.5.2, documentation updated on 21st February, 2008.
See About this document... for information on suggesting changes.
|