Linux/Unix > Python Essential Reference, Second Edition > B. Extending and Embedding Python > Reference Counting | See All Titles

< BACK | Make Note | Bookmark | CONTINUE >

155117184014003188065099048180054212144238241179195140058238111161105095080115231005169016

### Reference Counting

Unlike programs written in Python, C extensions have to manipulate the reference count of Python objects. This is done using the following macros:

Macro | Description
--- | ---
`Py_INCREF(``obj` `)` | Increments the reference count of `obj` , which must be non-`NULL`
`Py_DECREF(``obj` `)` | Decrements the reference count of `obj` , which must be non-`NULL`
`Py_XINCREF(``obj` `)` | Increments the reference count of `obj` , which may be `NULL`
`Py_XDECREF(``obj` `)` | Decrements the reference count of `obj` , which may be `NULL`

Manipulating the reference count of Python objects in C is a delicate topic, and readers are strongly advised to consult the “Extending and Embedding the Python Interpreter” document available at http://www.python.org/doc/ext before proceeding any further. With this in mind, all Python objects are manipulated in C through the use of pointers of type `PyObject *`. Furthermore, these pointers are classified into two categories: owned references and borrowed references. An owned reference is a pointer to a Python object in which the reference count of that object has been updated to reflect the fact that some piece of C code or a C data structure is holding a pointer to it. A borrowed reference, on the other hand, is simply a bare pointer to a Python object in which the reference count of the object has not been updated.

Owned references are most commonly created by functions that create new Python objects, such as `Py_BuildValue()`, `PyInt_FromLong()`, and `PyList_New()`. When called, a new Python object is created and the object is said to be owned by the calling function. Borrowed references often appear when a function obtains a pointer to a Python object from elsewhere or when the contents of Python objects such as lists and dictionaries are extracted. For example, the `self` and `args` parameters of a wrapper function are borrowed references, as is the pointer returned by functions such as `PyList_GetItem()`.

The owner of a reference must either give up ownership using the `Py_DECREF()` macro or transfer ownership elsewhere. For example, temporary objects created inside a wrapper function should be destroyed using `Py_DECREF()`, whereas the return value of a wrapper is an owned reference that’s given back to the interpreter. Likewise, the holder of a borrowed reference can obtain ownership using the `Py_INCREF()` macro. However, special care is in order. For example, decrementing the reference count of a borrowed reference may cause the interpreter to crash with a segmentation fault at a later time during execution. Likewise, failure to release an owned reference or inadvertently increasing the reference count of an object will lead to memory leaks.

Figuring out Python’s reference-counting scheme is tricky because there are several inconsistencies in its treatment of references. However, here are a few general rules:

- Functions that create new Python objects always return owned references.

- If you want to save a reference to a Python object, use `Py_INCREF()` to increase the reference count.

- To dispose of an owned reference, use `Py_DECREF()`.

- Many (but not all) functions that return pointers to objects contained in sequences and mapping objects return owned references.

- Many (but not all) functions that store objects in containers such as sequences and mappings increase the reference count of objects they contain.

- All C wrapper functions must return an owned reference.

Exceptions to these rules are noted in later sections of this appendix.

| Last updated on 3/28/2002 Python Essential Reference, Second Edition, © 2002 New Riders Publishing

< BACK | Make Note | Bookmark | CONTINUE >

© 2002, O'Reilly & Associates, Inc.