Reference Counting¶

The functions and macros in this section are used for managing reference countsof Python objects.

Py_ssize_tPy_REFCNT(PyObject*o)¶

Get the reference count of the Python objecto.

Note that the returned value may not actually reflect how manyreferences to the object are actually held. For example, someobjects areimmortal and have a very high refcount that does notreflect the actual number of references. Consequently, do not relyon the returned value to be accurate, other than a value of 0 or 1.

Use thePy_SET_REFCNT() function to set an object reference count.

Changed in version 3.10:Py_REFCNT() is changed to the inline static function.

Changed in version 3.11:The parameter type is no longerconstPyObject*.

voidPy_SET_REFCNT(PyObject*o,Py_ssize_trefcnt)¶

Set the objecto reference counter torefcnt.

OnPython build with Free Threading, ifrefcnt is larger thanUINT32_MAX, the object is madeimmortal.

This function has no effect onimmortal objects.

Added in version 3.9.

Changed in version 3.12:Immortal objects are not modified.

voidPy_INCREF(PyObject*o)¶

Indicate taking a newstrong reference to objecto,indicating it is in use and should not be destroyed.

This function has no effect onimmortal objects.

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

When done using the object, release is by callingPy_DECREF().

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

Do not expect this function to actually modifyo in any way.For at leastsome objects,this function has no effect.

Changed in version 3.12:Immortal objects are not modified.

voidPy_XINCREF(PyObject*o)¶

Similar toPy_INCREF(), but the objecto can beNULL,in which case this 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:callPy_INCREF() ono and return the objecto.

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

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().

Added 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.

Added in version 3.10.

voidPy_DECREF(PyObject*o)¶

Release astrong reference to objecto, indicating thereference is no longer used.

This function has no effect onimmortal objects.

Once the laststrong reference is released(i.e. the object’s reference count reaches 0),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().

Do not expect this function to actually modifyo in any way.For at leastsome objects,this function has no effect.

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.

Changed in version 3.12:Immortal objects are not modified.

voidPy_XDECREF(PyObject*o)¶

Similar toPy_DECREF(), but the objecto can beNULL,in which case this has no effect.The same warning fromPy_DECREF() applies here as well.

voidPy_CLEAR(PyObject*o)¶

Release astrong reference 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 releasing the reference.

It is a good idea to use this macro whenever releasing a referenceto an object that might be traversed during garbage collection.

Changed in version 3.12:The macro argument is now only evaluated once. If the argument has sideeffects, these are no longer duplicated.

voidPy_IncRef(PyObject*o)¶

Part of theStable ABI.

Indicate taking a newstrong reference to objecto.A function version ofPy_XINCREF().It can be used for runtime dynamic embedding of Python.

voidPy_DecRef(PyObject*o)¶

Part of theStable ABI.

Release astrong reference to objecto.A function version ofPy_XDECREF().It can be used for runtime dynamic embedding of Python.

Py_SETREF(dst,src)¶

Macro safely releasing astrong reference to objectdstand settingdst tosrc.

As in case ofPy_CLEAR(), “the obvious” code can be deadly:

Py_DECREF(dst);dst=src;

The safe way is:

Py_SETREF(dst,src);

That arranges to setdst tosrc _before_ releasing the referenceto the old value ofdst, so that any code triggered as a side-effectofdst getting torn down no longer believesdst pointsto a valid object.

Added in version 3.6.

Changed in version 3.12:The macro arguments are now only evaluated once. If an argument has sideeffects, these are no longer duplicated.

Py_XSETREF(dst,src)¶

Variant ofPy_SETREF macro that usesPy_XDECREF() insteadofPy_DECREF().

Added in version 3.6.

Changed in version 3.12:The macro arguments are now only evaluated once. If an argument has sideeffects, these are no longer duplicated.