Reference Counting

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

Py_ssize_t Py_REFCNT(PyObject *o)

Get the reference count of the Python object o.

Use the Py_SET_REFCNT() function to set an object reference count.

Modifié dans la version 3.11: The parameter type is no longer const PyObject*.

Modifié dans la version 3.10: Py_REFCNT() is changed to the inline static function.

void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)

Set the object o reference counter to refcnt.

Nouveau dans la version 3.9.

void Py_INCREF(PyObject *o)

Incrémente le compteur de références de l'objet o.

Cette fonction est souvent utilisée pour convertir une référence empruntée en une référence forte sur place. La fonction Py_NewRef() peut être utilisée pour créer une nouvelle référence forte.

L'objet ne doit pas être NULL, la fonction Py_XINCREF() doit être utilisée s'il est possible qu'il soit NULL.

void Py_XINCREF(PyObject *o)

Incrémente le compteur de références de l'objet o. La macro n'a pas d'effet si l'objet est NULL.

Voir aussi Py_XNewRef().

PyObject *Py_NewRef(PyObject *o)

Part of the Stable ABI since version 3.10.

Créer une nouvelle référence forte d'un objet : incrémente le compteur de référence de l'objet o et renvoie l'objet o.

Py_DECREF() doit être appelée quand la référence forte n'est plus utilisée pour décrémenter le compteur de références de l'objet.

L'objet o ne doit pas être NULL et la fonction Py_XNewRef() doit être utilisée si o peut être NULL.

Par exemple :

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

peut s'écrire :

self->attr = Py_NewRef(obj);

Voir aussi Py_INCREF().

Nouveau dans la version 3.10.

PyObject *Py_XNewRef(PyObject *o)

Part of the Stable ABI since version 3.10.

Semblable à Py_NewRef() mais l'objet o peut être NULL.

Cette fonction renvoie NULL si l'objet o est NULL.

Nouveau dans la version 3.10.

void Py_DECREF(PyObject *o)

Décrémente le compteur de références de l'objet o.

Si le compteur de références atteint zéro, la fonction de dés-allocation du type de l'objet (qui ne doit pas être NULL) est invoquée.

Cette fonction est généralement utilisée pour supprimer une référence forte avant qu'elle ne soit plus accessible.

L'objet en argument ne doit pas être NULL. Py_XDECREF() doit être utilisée si l'objet peut être NULL.

Avertissement

La fonction de dés-allocation peut invoquer du code Python arbitraire (par exemple quand une instance d'une classe avec une méthode __del__() est supprimée). Le code exécuté a accès à toutes les variables Python globales mais les exceptions lors de l'exécution de ce code ne sont pas propagées. Tous les objets qui peuvent être atteints à partir d'une variable globale doivent être dans un état cohérent avant d'appeler Py_DECREF(). Par exemple le code pour supprimer un élément d'une liste doit copier une référence à l'objet dans une variable temporaire, mettre à jour la liste, et enfin appeler Py_DECREF() avec la variable temporaire.

void Py_XDECREF(PyObject *o)

Décrémente le compteur de références de l'objet o. L'objet peut être NULL, dans ce cas la macro n'a pas d'effet. Dans le cas contraire le comportement est identique à Py_DECREF() et les mêmes avertissements sont de rigueur.

void Py_CLEAR(PyObject *o)

Décrémente le compteur de références de l'objet o. L'objet peut être NULL, dans ce cas la macro n'a pas d'effet. Dans le cas contraire le comportement est identique à Py_DECREF(), puis l'argument est mis à NULL. L'avertissement au sujet de l'objet passé en argument à Py_DECREF() ne s'applique pas car la macro utilise une variable temporaire et met l'objet à NULL avant de décrémenter le compteur de références.

Il est recommandé d'utiliser cette macro lorsqu'on décrémente le compteur de référence d'un objet qui peut être parcouru par le ramasse-miette.

Modifié dans la version 3.12: The macro argument is now only evaluated once. If the argument has side effects, these are no longer duplicated.

void Py_IncRef(PyObject *o)

Part of the Stable ABI.

Incrémente le compteur de références de l'objet o. C'est la version fonctionnelle de Py_XINCREF(). Elle peut être utilisée lorsque Python est embarqué dynamiquement dans une application.

void Py_DecRef(PyObject *o)

Part of the Stable ABI.

Décrémente le compteur de références de l'objet o. C'est la version fonctionnelle de Py_XDECREF(). Elle peut être utilisée lorsque Python est embarqué dynamiquement dans une application.

Py_SETREF(dst, src)

Macro safely decrementing the dst reference count and setting dst to src.

As in case of Py_CLEAR(), "the obvious" code can be deadly:

Py_DECREF(dst);
dst = src;

The safe way is:

Py_SETREF(dst, src);

That arranges to set dst to src _before_ decrementing reference count of dst old value, so that any code triggered as a side-effect of dst getting torn down no longer believes dst points to a valid object.

Nouveau dans la version 3.6.

Modifié dans la version 3.12: The macro arguments are now only evaluated once. If an argument has side effects, these are no longer duplicated.

Py_XSETREF(dst, src)

Variant of Py_SETREF macro that uses Py_XDECREF() instead of Py_DECREF().

Nouveau dans la version 3.6.

Modifié dans la version 3.12: The macro arguments are now only evaluated once. If an argument has side effects, these are no longer duplicated.