gc — Schnittstelle des Garbage Collectors

---

Dieses Modul stellt eine Schnittstelle zum optionalen Garbage Collector bereit. Es ermöglicht das Deaktivieren des Collectors, die Feinabstimmung der Sammelfrequenz und das Festlegen von Debugging-Optionen. Es bietet auch Zugriff auf nicht erreichbare Objekte, die vom Collector gefunden, aber nicht freigegeben werden konnten. Da der Collector die in Python bereits verwendete Referenzzählung ergänzt, können Sie den Collector deaktivieren, wenn Sie sicher sind, dass Ihr Programm keine Referenzzyklen erstellt. Die automatische Sammlung kann durch Aufruf von gc.disable() deaktiviert werden. Zum Debuggen eines speicherfressenden Programms rufen Sie gc.set_debug(gc.DEBUG_LEAK) auf. Beachten Sie, dass dies gc.DEBUG_SAVEALL einschließt, wodurch vom Garbage Collector gesammelte Objekte zur Inspektion in gc.garbage gespeichert werden.

Das Modul gc stellt folgende Funktionen bereit:

gc.enable()

Automatische Garbage Collection aktivieren.

gc.disable()

Automatische Garbage Collection deaktivieren.

gc.isenabled()

Gibt True zurück, wenn die automatische Sammlung aktiviert ist.

gc.collect(generation=2)

Eine Sammlung durchführen. Das optionale Argument generation kann eine Ganzzahl sein, die angibt, welche Generation gesammelt werden soll (von 0 bis 2). Ein ValueError wird ausgelöst, wenn die Generationsnummer ungültig ist. Die Summe der gesammelten und nicht sammelbaren Objekte wird zurückgegeben.

Der Aufruf von gc.collect(0) führt eine GC-Sammlung der jungen Generation durch.

Der Aufruf von gc.collect(1) führt eine GC-Sammlung der jungen Generation und ein Inkrement der alten Generation durch.

Der Aufruf von gc.collect(2) oder gc.collect() führt eine vollständige Sammlung durch.

Die für eine Reihe von eingebauten Typen geführten Freilisten werden gelöscht, wann immer eine vollständige Sammlung oder die Sammlung der höchsten Generation (2) ausgeführt wird. Nicht alle Elemente in einigen Freilisten können aufgrund der spezifischen Implementierung freigegeben werden, insbesondere float.

Die Auswirkung des Aufrufs von gc.collect(), während der Interpreter bereits eine Sammlung durchführt, ist undefiniert.

Geändert in Version 3.14: generation=1 führt eine Inkrement-Sammlung durch.

gc.set_debug(flags)

Setzt die Debugging-Flags der Garbage Collection. Debugging-Informationen werden nach sys.stderr geschrieben. Siehe unten für eine Liste von Debugging-Flags, die mit bitweisen Operationen kombiniert werden können, um das Debugging zu steuern.

gc.get_debug()

Gibt die aktuell gesetzten Debugging-Flags zurück.

gc.get_objects(generation=None)

Gibt eine Liste aller vom Collector verfolgten Objekte zurück, ausgenommen die zurückgegebene Liste. Wenn generation nicht None ist, werden nur die Objekte wie folgt zurückgegeben:

• 0: Alle Objekte in der jungen Generation

• 1: Keine Objekte, da es keine Generation 1 gibt (Stand Python 3.14)

• 2: Alle Objekte in der alten Generation

Geändert in Version 3.8: Neuer Parameter generation.

Geändert in Version 3.14: Generation 1 wird entfernt

Löst ein Auditing-Ereignis gc.get_objects mit dem Argument generation aus.

gc.get_stats()

Gibt eine Liste von drei pro Generation befindlichen Dictionaries zurück, die Sammelstatistiken seit dem Start des Interpreters enthalten. Die Anzahl der Schlüssel kann sich in Zukunft ändern, aber derzeit enthält jedes Dictionary die folgenden Elemente:

• collections ist die Anzahl der Male, die diese Generation gesammelt wurde;

• collected ist die Gesamtzahl der in dieser Generation gesammelten Objekte;

• uncollectable ist die Gesamtzahl der Objekte, die als nicht sammelbar befunden wurden (und daher in die Liste garbage verschoben wurden) innerhalb dieser Generation.

Hinzugefügt in Version 3.4.

gc.set_threshold(threshold0[, threshold1[, threshold2]])

Legt die Schwellenwerte für die Garbage Collection fest (die Sammelfrequenz). Das Setzen von threshold0 auf Null deaktiviert die Sammlung.

Der GC klassifiziert Objekte in zwei Generationen, je nachdem, ob sie eine Sammlung überstanden haben. Neue Objekte werden in der jungen Generation platziert. Wenn ein Objekt eine Sammlung übersteht, wird es in die alte Generation verschoben.

Um zu entscheiden, wann eine Sammlung durchgeführt werden soll, verfolgt der Collector die Anzahl der Objektzuweisungen und -freigaben seit der letzten Sammlung. Wenn die Anzahl der Zuweisungen abzüglich der Anzahl der Freigaben threshold0 überschreitet, beginnt die Sammlung. Bei jeder Sammlung werden alle Objekte in der jungen Generation und ein Teil der alten Generation gesammelt.

Im Thread-freien Build wird auch die Zunahme der Prozessspeichernutzung vor der Ausführung des Collectors geprüft. Wenn die Speichernutzung seit der letzten Sammlung nicht um 10 % gestiegen ist und die Nettoanzahl der Objektzuweisungen das 40-fache von threshold0 nicht überschritten hat, wird die Sammlung nicht durchgeführt.

Der Bruchteil der alten Generation, der gesammelt wird, ist **umgekehrt proportional** zu threshold1. Je größer threshold1 ist, desto langsamer werden Objekte in der alten Generation gesammelt. Bei dem Standardwert von 10 wird während jeder Sammlung 1 % der alten Generation gescannt.

threshold2 wird ignoriert.

Siehe Entwurf des Garbage Collectors für weitere Informationen.

Geändert in Version 3.14: threshold2 wird ignoriert.

gc.get_count()

Gibt die aktuellen Sammlungszähler als Tupel von (count0, count1, count2) zurück.

gc.get_threshold()

Gibt die aktuellen Sammelschwellenwerte als Tupel von (threshold0, threshold1, threshold2) zurück.

gc.get_referrers(*objs)

Gibt die Liste der Objekte zurück, die direkt auf eines der objs verweisen. Diese Funktion findet nur Container, die Garbage Collection unterstützen; Erweiterungstypen, die auf andere Objekte verweisen, aber keine Garbage Collection unterstützen, werden nicht gefunden.

Beachten Sie, dass Objekte, die bereits dereferenziert wurden, aber in Zyklen leben und noch nicht vom Garbage Collector gesammelt wurden, unter den resultierenden Referenzgebern aufgeführt werden können. Um nur aktuell lebende Objekte zu erhalten, rufen Sie collect() auf, bevor Sie get_referrers() aufrufen.

Warnung

Vorsicht ist geboten, wenn Sie von get_referrers() zurückgegebene Objekte verwenden, da einige davon noch im Aufbau begriffen und somit in einem vorübergehend ungültigen Zustand sein könnten. Vermeiden Sie die Verwendung von get_referrers() für andere Zwecke als das Debugging.

Löst ein Auditing-Ereignis gc.get_referrers mit dem Argument objs aus.

gc.get_referents(*objs)

Gibt eine Liste von Objekten zurück, auf die direkt durch eines der Argumente verwiesen wird. Die zurückgegebenen Referenzziele sind die Objekte, die von den C-Level tp_traverse-Methoden (falls vorhanden) der Argumente besucht werden, und sind möglicherweise nicht alle tatsächlich direkt erreichbaren Objekte. tp_traverse-Methoden werden nur von Objekten unterstützt, die Garbage Collection unterstützen, und sind nur erforderlich, um Objekte zu besuchen, die an einem Zyklus beteiligt sein könnten. Wenn beispielsweise eine Ganzzahl direkt von einem Argument erreichbar ist, kann dieses Ganzzahl-Objekt in der Ergebnisliste erscheinen oder auch nicht.

Löst ein Auditing-Ereignis gc.get_referents mit dem Argument objs aus.

gc.is_tracked(obj)

Gibt True zurück, wenn das Objekt derzeit vom Garbage Collector verfolgt wird, andernfalls False. Als allgemeine Regel werden Instanzen atomarer Typen nicht verfolgt und Instanzen nicht-atomarer Typen (Container, benutzerdefinierte Objekte...) verfolgt. Es können jedoch einige typspezifische Optimierungen vorhanden sein, um den Fußabdruck des Garbage Collectors für einfache Instanzen zu unterdrücken (z. B. Dictionaries, die nur atomare Schlüssel und Werte enthalten).

>>> gc.is_tracked(0)
False
>>> gc.is_tracked("a")
False
>>> gc.is_tracked([])
True
>>> gc.is_tracked({})
False
>>> gc.is_tracked({"a": 1})
True

Hinzugefügt in Version 3.1.

gc.is_finalized(obj)

Gibt True zurück, wenn das angegebene Objekt vom Garbage Collector finalisiert wurde, andernfalls False.

>>> x = None
>>> class Lazarus:
...     def __del__(self):
...         global x
...         x = self
...
>>> lazarus = Lazarus()
>>> gc.is_finalized(lazarus)
False
>>> del lazarus
>>> gc.is_finalized(x)
True

Hinzugefügt in Version 3.9.

gc.freeze()

Friert alle vom Garbage Collector verfolgten Objekte ein; verschiebt sie in eine permanente Generation und ignoriert sie bei allen zukünftigen Sammlungen.

Wenn ein Prozess fork() ohne exec() aufruft, maximiert das Vermeiden unnötiger Copy-on-Write-Operationen in Kindprozessen die Speicherfreigabe und reduziert die Gesamtspeichernutzung. Dies erfordert sowohl die Vermeidung der Erstellung von freien „Löchern“ in Speicherseiten im Elternprozess als auch die Sicherstellung, dass GC-Sammlungen in Kindprozessen den gc_refs-Zähler von langlebigen Objekten aus dem Elternprozess nicht berühren. Um beides zu erreichen, rufen Sie gc.disable() frühzeitig im Elternprozess auf, gc.freeze() kurz vor fork() und gc.enable() frühzeitig in den Kindprozessen.

Hinzugefügt in Version 3.7.

gc.unfreeze()

Entfroren Sie die Objekte in der permanenten Generation und legen Sie sie zurück in die älteste Generation.

Hinzugefügt in Version 3.7.

gc.get_freeze_count()

Gibt die Anzahl der Objekte in der permanenten Generation zurück.

Hinzugefügt in Version 3.7.

Die folgenden Variablen stehen schreibgeschützt zur Verfügung (Sie können die Werte ändern, sollten sie aber nicht neu zuweisen)

gc.garbage

Eine Liste von Objekten, die der Collector als unerreichbar, aber nicht freigebbar identifiziert hat (nicht sammelbare Objekte). Ab Python 3.4 sollte diese Liste die meiste Zeit leer sein, außer bei der Verwendung von Instanzen von C-Erweiterungstypen mit einem nicht-NULL tp_del Slot.

Wenn DEBUG_SAVEALL gesetzt ist, werden alle unerreichbaren Objekte zur Liste garbage hinzugefügt, anstatt freigegeben zu werden.

Geändert in Version 3.2: Wenn diese Liste beim Herunterfahren des Interpreters nicht leer ist, wird eine ResourceWarning ausgegeben, die standardmäßig still ist. Wenn DEBUG_UNCOLLECTABLE gesetzt ist, wird zusätzlich der Inhalt der Liste garbage ausgegeben.

Geändert in Version 3.4: Nach PEP 442 landen Objekte mit einer Methode __del__() nicht mehr in gc.garbage.

gc.callbacks

Eine Liste von Rückruffunktionen, die vom Garbage Collector vor und nach der Sammlung aufgerufen werden. Die Rückruffunktionen werden mit zwei Argumenten, phase und info, aufgerufen.

phase kann einer von zwei Werten sein:

„start“: Die Garbage Collection wird gleich beginnen.

„stop“: Die Garbage Collection wurde beendet.

info ist ein Dictionary, das weitere Informationen für den Rückruf liefert. Die folgenden Schlüssel sind derzeit definiert:

„generation“: Die älteste zu sammelnde Generation.

„collected“: Wenn phase „stop“ ist, die Anzahl der erfolgreich gesammelten Objekte.

„uncollectable“: Wenn phase „stop“ ist, die Anzahl der Objekte, die nicht gesammelt werden konnten und in garbage platziert wurden.

Anwendungen können ihre eigenen Rückruffunktionen zu dieser Liste hinzufügen. Die Hauptanwendungsfälle sind:

Sammeln von Statistiken zur Garbage Collection, z. B. wie oft verschiedene Generationen gesammelt werden und wie lange die Sammlung dauert.

Ermöglichen von Anwendungen, ihre eigenen nicht sammelbaren Typen zu identifizieren und zu bereinigen, wenn sie in garbage erscheinen.

Hinzugefügt in Version 3.3.

Die folgenden Konstanten stehen für die Verwendung mit set_debug() zur Verfügung:

gc.DEBUG_STATS

Gibt während der Sammlung Statistiken aus. Diese Informationen können beim Abstimmen der Sammelfrequenz nützlich sein.

gc.DEBUG_COLLECTABLE

Gibt Informationen über gefundene sammelbare Objekte aus.

gc.DEBUG_UNCOLLECTABLE

Gibt Informationen über gefundene nicht sammelbare Objekte aus (Objekte, die nicht erreichbar, aber nicht vom Collector freigegeben werden können). Diese Objekte werden der Liste garbage hinzugefügt.

Geändert in Version 3.2: Gibt außerdem den Inhalt der Liste garbage beim Herunterfahren des Interpreters aus, wenn diese nicht leer ist.

gc.DEBUG_SAVEALL

Wenn gesetzt, werden alle gefundenen unerreichbaren Objekte an garbage angehängt, anstatt freigegeben zu werden. Dies kann beim Debuggen eines speicherfressenden Programms hilfreich sein.

gc.DEBUG_LEAK

Die Debugging-Flags, die für den Collector erforderlich sind, um Informationen über ein speicherfressendes Programm auszugeben (gleich DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | DEBUG_SAVEALL).