Referenzzählung

Die Funktionen und Makros in diesem Abschnitt werden zur Verwaltung von Referenzzählungen von Python-Objekten verwendet.

Py_ssize_t Py_REFCNT(PyObject *o)
Teil des Stable ABI seit Version 3.14.

Gibt die Referenzzählung des Python-Objekts o zurück.

Beachten Sie, dass der zurückgegebene Wert möglicherweise nicht tatsächlich widerspiegelt, wie viele Referenzen auf das Objekt tatsächlich gehalten werden. Zum Beispiel sind einige Objekte unsterblich und haben eine sehr hohe Referenzzählung, die nicht die tatsächliche Anzahl der Referenzen widerspiegelt. Folglich sollten Sie sich nicht auf den zurückgegebenen Wert als genau verlassen, außer bei Werten von 0 oder 1.

Verwenden Sie die Funktion Py_SET_REFCNT(), um die Referenzzählung eines Objekts festzulegen.

Hinweis

Bei frei-threaded Builds von Python ist die Rückgabe von 1 nicht ausreichend, um festzustellen, ob es sicher ist, o so zu behandeln, als ob es von anderen Threads nicht aufgerufen würde. Verwenden Sie stattdessen PyUnstable_Object_IsUniquelyReferenced().

Siehe auch die Funktion PyUnstable_Object_IsUniqueReferencedTemporary().

Geändert in Version 3.10: Py_REFCNT() wird zu einer inline statischen Funktion geändert.

Geändert in Version 3.11: Der Parametertyp ist nicht mehr const PyObject*.

void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)

Setzt den Referenzzähler des Objekts o auf refcnt.

Bei Python-Builds mit Free Threading, wenn refcnt größer als UINT32_MAX ist, wird das Objekt unsterblich gemacht.

Diese Funktion hat keine Auswirkung auf unsterbliche Objekte.

Hinzugefügt in Version 3.9.

Geändert in Version 3.12: Unsterbliche Objekte werden nicht modifiziert.

void Py_INCREF(PyObject *o)

Zeigt an, dass eine neue starke Referenz auf das Objekt o genommen wird, was darauf hindeutet, dass es in Gebrauch ist und nicht zerstört werden sollte.

Diese Funktion hat keine Auswirkung auf unsterbliche Objekte.

Diese Funktion wird normalerweise verwendet, um eine geliehene Referenz vor Ort in eine starke Referenz umzuwandeln. Die Funktion Py_NewRef() kann verwendet werden, um eine neue starke Referenz zu erstellen.

Wenn das Objekt nicht mehr benötigt wird, wird Py_DECREF() aufgerufen.

Das Objekt darf nicht NULL sein; wenn Sie nicht sicher sind, dass es nicht NULL ist, verwenden Sie Py_XINCREF().

Erwarten Sie nicht, dass diese Funktion o tatsächlich in irgendeiner Weise modifiziert. Für zumindest einige Objekte hat diese Funktion keine Auswirkung.

Geändert in Version 3.12: Unsterbliche Objekte werden nicht modifiziert.

void Py_XINCREF(PyObject *o)

Ähnlich wie Py_INCREF(), aber das Objekt o kann NULL sein, in welchem Fall dies keine Auswirkung hat.

Siehe auch Py_XNewRef().

PyObject *Py_NewRef(PyObject *o)
Teil der Stable ABI seit Version 3.10.

Erstellt eine neue starke Referenz auf ein Objekt: ruft Py_INCREF() für o auf und gibt das Objekt o zurück.

Wenn die starke Referenz nicht mehr benötigt wird, sollte Py_DECREF() darauf aufgerufen werden, um die Referenz freizugeben.

Das Objekt o darf nicht NULL sein; verwenden Sie Py_XNewRef(), wenn o NULL sein kann.

Zum Beispiel

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

kann geschrieben werden als

self->attr = Py_NewRef(obj);

Siehe auch Py_INCREF().

Hinzugefügt in Version 3.10.

PyObject *Py_XNewRef(PyObject *o)
Teil der Stable ABI seit Version 3.10.

Ähnlich wie Py_NewRef(), aber das Objekt o kann NULL sein.

Wenn das Objekt o NULL ist, gibt die Funktion einfach NULL zurück.

Hinzugefügt in Version 3.10.

void Py_DECREF(PyObject *o)

Gibt eine starke Referenz auf das Objekt o frei, was darauf hindeutet, dass die Referenz nicht mehr verwendet wird.

Diese Funktion hat keine Auswirkung auf unsterbliche Objekte.

Sobald die letzte starke Referenz freigegeben ist (d. h. die Referenzzählung des Objekts 0 erreicht), wird die Deallokationsfunktion des Typs des Objekts (die nicht NULL sein darf) aufgerufen.

Diese Funktion wird normalerweise verwendet, um eine starke Referenz zu löschen, bevor ihr Gültigkeitsbereich verlassen wird.

Das Objekt darf nicht NULL sein; wenn Sie nicht sicher sind, dass es nicht NULL ist, verwenden Sie Py_XDECREF().

Erwarten Sie nicht, dass diese Funktion o tatsächlich in irgendeiner Weise modifiziert. Für zumindest einige Objekte hat diese Funktion keine Auswirkung.

Warnung

Die Deallokationsfunktion kann beliebigen Python-Code aufrufen (z. B. wenn eine Klasseninstanz mit einer Methode __del__() deallokiert wird). Obwohl Ausnahmen in solchem Code nicht propagiert werden, hat der ausgeführte Code freien Zugriff auf alle Python-Globalvariablen. Das bedeutet, dass jedes Objekt, das von einer Globalvariablen erreichbar ist, in einem konsistenten Zustand sein sollte, bevor Py_DECREF() aufgerufen wird. Zum Beispiel sollte Code zum Löschen eines Objekts aus einer Liste eine Referenz auf das gelöschte Objekt in einer temporären Variable kopieren, die Listen-Datenstruktur aktualisieren und dann Py_DECREF() für die temporäre Variable aufrufen.

Geändert in Version 3.12: Unsterbliche Objekte werden nicht modifiziert.

void Py_XDECREF(PyObject *o)

Ähnlich wie Py_DECREF(), aber das Objekt o kann NULL sein, in welchem Fall dies keine Auswirkung hat. Die gleiche Warnung von Py_DECREF() gilt auch hier.

void Py_CLEAR(PyObject *o)

Gibt eine starke Referenz für das Objekt o frei. Das Objekt kann NULL sein, in welchem Fall das Makro keine Auswirkung hat; andernfalls ist die Auswirkung dieselbe wie bei Py_DECREF(), außer dass das Argument auch auf NULL gesetzt wird. Die Warnung für Py_DECREF() gilt nicht für das übergebene Objekt, da das Makro sorgfältig eine temporäre Variable verwendet und das Argument vor der Freigabe der Referenz auf NULL setzt.

Es ist ratsam, dieses Makro immer dann zu verwenden, wenn eine Referenz auf ein Objekt freigegeben wird, das während der Garbage Collection durchlaufen werden könnte.

Geändert in Version 3.12: Das Makroargument wird nun nur einmal ausgewertet. Wenn ein Argument Nebeneffekte hat, werden diese nicht mehr dupliziert.

void Py_IncRef(PyObject *o)
Teil der Stable ABI.

Zeigt an, dass eine neue starke Referenz auf das Objekt o genommen wird. Eine Funktionsversion von Py_XINCREF(). Sie kann für die Laufzeit-dynamische Einbettung von Python verwendet werden.

void Py_DecRef(PyObject *o)
Teil der Stable ABI.

Gibt eine starke Referenz auf das Objekt o frei. Eine Funktionsversion von Py_XDECREF(). Sie kann für die Laufzeit-dynamische Einbettung von Python verwendet werden.

Py_SETREF(dst, src)

Makro, das sicher eine starke Referenz auf das Objekt dst freigibt und dst auf src setzt.

Wie im Fall von Py_CLEAR() kann der „offensichtliche“ Code tödlich sein

Py_DECREF(dst);
dst = src;

Der sichere Weg ist

Py_SETREF(dst, src);

Dies bewirkt, dass dst auf src gesetzt wird, *bevor* die Referenz auf den alten Wert von dst freigegeben wird, so dass jeder Code, der als Nebeneffekt des Abbauens von dst ausgelöst wird, nicht mehr glaubt, dass dst auf ein gültiges Objekt verweist.

Hinzugefügt in Version 3.6.

Geändert in Version 3.12: Die Makroargumente werden nun nur einmal ausgewertet. Wenn ein Argument Nebeneffekte hat, werden diese nicht mehr dupliziert.

Py_XSETREF(dst, src)

Variante des Makros Py_SETREF, das Py_XDECREF() anstelle von Py_DECREF() verwendet.

Hinzugefügt in Version 3.6.

Geändert in Version 3.12: Die Makroargumente werden nun nur einmal ausgewertet. Wenn ein Argument Nebeneffekte hat, werden diese nicht mehr dupliziert.