< BACKMake Note | BookmarkCONTINUE >
152015024128143245168232148039196038240039088173205162105045222218072221087111231141199

Reference Counting

The macros in this section are used for managing reference counts of Python objects.

					
void Py_INCREF(PyObject *o)

				

Increments the reference count for object o. The object must not be NULL; if you aren't sure that it isn't NULL, use Py_XINCREF().

					
void Py_XINCREF(PyObject *o)

				

Increments the reference count for object o. The object might be NULL, in which case the macro has no effect.

					
void Py_DECREF(PyObject *o)

				

Decrements the reference count for object o. The object must not be NULL; if you aren't sure that it isn't NULL, use Py_XDECREF(). If the reference count reaches zero, the object's type's deallocation function (which must not be NULL) is invoked.

Caution

The deallocation function can cause arbitrary Python code to be invoked (for example, when a class instance with a __del__() method is deallocated). Although exceptions in such code are not propagated, the executed code has free access to all Python global variables. This means that any object reachable from a global variable should be in a consistent state before Py_DECREF() is invoked. For example, code to delete an object from a list should copy a reference to the deleted object in a temporary variable, update the list data structure, and then call Py_DECREF() for the temporary variable.



					
void Py_XDECREF(PyObject *o)

				

Decrements the reference count for object o. The object might be NULL, in which case the macro has no effect; otherwise the effect is the same as for Py_DECREF(), and the same caution applies.

The following functions or macros are only for use within the interpreter core: _Py_Dealloc(), _Py_ForgetReference(), _Py_NewReference(), as well as the global variable _Py_RefTotal.


Last updated on 1/30/2002
Python Developer's Handbook, © 2002 Sams Publishing

< BACKMake Note | BookmarkCONTINUE >

Index terms contained in this section

Application Programmers Interface (API)
     Python/C
            managing reference counts, Python objects
counts
     reference
            managing, Python objects
deallocation function
functions
      deallocation
      managing reference counts, Python objects
interfaces
     Python/C Application Programmers (API)
            managing reference counts, Python objects
macros
      Py_DECREF()
managing
      reference counts, Python objects
objects
     Python
            managing reference counts
Py_DECREF() macro
Python/C Application Programmers Interface (API)
      managing reference counts, Python objects
reference counts
      managing, Python objects

© 2002, O'Reilly & Associates, Inc.