Reference Counting¶
The macros in this section are used for managing reference counts of Pythonobjects.
- voidPy_INCREF(PyObject*o)¶
Indicate taking a newstrong reference to objecto,indicating it is in use and should not be destroyed.
This function is usually used to convert aborrowed reference to astrong reference in-place. The
Py_NewRef()function can beused to create a newstrong reference.When done using the object, release it by calling
Py_DECREF().The object must not be
NULL; if you aren’t sure that it isn’tNULL, usePy_XINCREF().Do not expect this function to actually modifyo in any way.
- voidPy_XINCREF(PyObject*o)¶
Similar to
Py_INCREF(), but the objecto can beNULL,in which case this has no effect.See also
Py_XNewRef().
- PyObject*Py_NewRef(PyObject*o)¶
- Part of theStable ABI since version 3.10.
Create a newstrong reference to an object:call
Py_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 be
NULL; usePy_XNewRef()ifo can beNULL.For example:
Py_INCREF(obj);self->attr=obj;
can be written as:
self->attr=Py_NewRef(obj);
See also
Py_INCREF().New in version 3.10.
- PyObject*Py_XNewRef(PyObject*o)¶
- Part of theStable ABI since version 3.10.
Similar to
Py_NewRef(), but the objecto can be NULL.If the objecto is
NULL, the function just returnsNULL.New in version 3.10.
- voidPy_DECREF(PyObject*o)¶
Release astrong reference to objecto, indicating thereference is no longer used.
Once the laststrong reference is released(i.e. the object’s reference count reaches 0),the object’s type’s deallocationfunction (which must not be
NULL) is invoked.This function is usually used to delete astrong reference beforeexiting its scope.
The object must not be
NULL; if you aren’t sure that it isn’tNULL,usePy_XDECREF().Do not expect this function to actually modifyo in any way.
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)¶
Similar to
Py_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 be
NULL, 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.
- voidPy_IncRef(PyObject*o)¶
- Part of theStable ABI.
Indicate taking a newstrong reference to objecto.A function version of
Py_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 of
Py_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.