Reference Counting

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

voidPy_INCREF(PyObject *o)

Increment the reference count for objecto.

This function is usually used to convert aborrowed reference to astrong reference in-place. ThePy_NewRef() function can beused to create a newstrong reference.

The object must not beNULL; if you aren’t sure that it isn’tNULL, usePy_XINCREF().

voidPy_XINCREF(PyObject *o)

Increment the reference count for objecto. The object may beNULL, inwhich case the macro has no effect.

See alsoPy_XNewRef().

PyObject *Py_NewRef(PyObject *o)
Part of theStable ABI since version 3.10.

Create a newstrong reference to an object: increment the referencecount of the objecto and return the objecto.

When thestrong reference is no longer needed,Py_DECREF()should be called on it to decrement the object reference count.

The objecto must not beNULL; usePy_XNewRef() ifo can beNULL.

For example:

Py_INCREF(obj);self->attr=obj;

can be written as:

self->attr=Py_NewRef(obj);

See alsoPy_INCREF().

New in version 3.10.

PyObject *Py_XNewRef(PyObject *o)
Part of theStable ABI since version 3.10.

Similar toPy_NewRef(), but the objecto can be NULL.

If the objecto isNULL, the function just returnsNULL.

New in version 3.10.

voidPy_DECREF(PyObject *o)

Decrement the reference count for objecto.

If the reference count reaches zero, the object’s type’s deallocationfunction (which must not beNULL) is invoked.

This function is usually used to delete astrong reference beforeexiting its scope.

The object must not beNULL; if you aren’t sure that it isn’tNULL,usePy_XDECREF().

Warning

The deallocation function can cause arbitrary Python code to be invoked (e.g.when a class instance with a__del__() method is deallocated). Whileexceptions in such code are not propagated, the executed code has free access toall Python global variables. This means that any object that is reachable froma global variable should be in a consistent state beforePy_DECREF() isinvoked. For example, code to delete an object from a list should copy areference to the deleted object in a temporary variable, update the list datastructure, and then callPy_DECREF() for the temporary variable.

voidPy_XDECREF(PyObject *o)

Decrement the reference count for objecto. The object may beNULL, inwhich case the macro has no effect; otherwise the effect is the same as forPy_DECREF(), and the same warning applies.

voidPy_CLEAR(PyObject *o)

Decrement the reference count for objecto. The object may beNULL, inwhich case the macro has no effect; otherwise the effect is the same as forPy_DECREF(), except that the argument is also set toNULL. The warningforPy_DECREF() does not apply with respect to the object passed becausethe macro carefully uses a temporary variable and sets the argument toNULLbefore decrementing its reference count.

It is a good idea to use this macro whenever decrementing the referencecount of an object that might be traversed during garbage collection.

voidPy_IncRef(PyObject *o)
Part of theStable ABI.

Increment the reference count for objecto. A function version ofPy_XINCREF().It can be used for runtime dynamic embedding of Python.

voidPy_DecRef(PyObject *o)
Part of theStable ABI.

Decrement the reference count for objecto. A function version ofPy_XDECREF().It can be used for runtime dynamic embedding of Python.

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.