gc
--- Garbage Collector interface¶
Ce module constitue une interface au ramasse-miettes facultatif. Il permet de désactiver le ramasse-miettes ou de régler la fréquence des passages. Il fournit des options de débogage, et donne aussi accès aux objets qui ne peuvent pas être détruits bien qu'ils aient été détectés comme non référencés. Le ramasse-miettes vient en complément du système de comptage de références, et peut donc être désactivé pour du code qui ne crée aucun cycle de références. On le désactive avec gc.disable()
. Pour remonter à la source d'une fuite de mémoire, utilisez gc.set_debug(gc.DEBUG_LEAK)
. Notez que gc.DEBUG_LEAK
inclut gc.DEBUG_SAVEALL
. Cette dernière option fait que les objets inatteignables, au lieu d'être détruits, sont placés dans la liste gc.garbage
pour pouvoir y être examinés.
Le module gc
contient les fonctions suivantes :
- gc.enable()¶
Active le ramasse-miettes.
- gc.disable()¶
Désactive le ramasse-miettes.
- gc.isenabled()¶
Renvoie
True
ouFalse
selon que le ramasse-miettes est activé ou non.
- gc.collect(generation=2)¶
With no arguments, run a full collection. The optional argument generation may be an integer specifying which generation to collect (from 0 to 2). A
ValueError
is raised if the generation number is invalid. The sum of collected objects and uncollectable objects is returned.The free lists maintained for a number of built-in types are cleared whenever a full collection or collection of the highest generation (2) is run. Not all items in some free lists may be freed due to the particular implementation, in particular
float
.The effect of calling
gc.collect()
while the interpreter is already performing a collection is undefined.
- gc.set_debug(flags)¶
Change les options de débogage du ramasse-miettes, qui activent l'écriture d'informations sur
sys.stderr
. Une liste d'options se trouve plus bas. Les options peuvent se combiner par les opérateurs bit à bit.
- gc.get_debug()¶
Renvoie les options de débogage actives.
- gc.get_objects(generation=None)¶
Returns a list of all objects tracked by the collector, excluding the list returned. If generation is not
None
, return only the objects tracked by the collector that are in that generation.Modifié dans la version 3.8: ajout du paramètre generation.
Lève un événement d'audit
gc.get_objects
avec l'argumentgeneration
.
- gc.get_stats()¶
Renvoie une liste de trois dictionnaires, un par génération. Ils contiennent des statistiques sur l'action du ramasse-miettes depuis le lancement de l'interpréteur. Les clés actuellement présentes sont les suivantes (d'autres pourraient être ajoutées dans des versions ultérieures) :
collections
, le nombre de fois où cette génération a été examinée par le ramasse-miettes ;collected
, le nombre total d'objets qui ont été détruits alors qu'ils étaient dans cette génération ;uncollectable
, le nombre total d'objets qui ont été identifiés comme indestructibles (et donc ajoutés à la listegarbage
) au sein de cette génération.
Ajouté dans la version 3.4.
- gc.set_threshold(threshold0[, threshold1[, threshold2]])¶
Règle les seuils de déclenchement du ramasse-miettes, qui déterminent sa fréquence de passage. Si threshold0 est mis à zéro, le ramasse-miettes ne passe jamais.
Les objets sont répartis en trois générations en fonction du nombre de passages du ramasse-miettes qui les ont laissés intacts. Les objets fraîchement créés sont placés dans la génération la plus jeune, numéro 0. À chaque fois qu'un objet persiste à la suite d'un passage du ramasse-miettes, il monte d'une génération, ceci jusqu'à la génération 2, la plus âgée. Le ramasse-miettes se déclenche en fonction du nombre d'allocations et de destructions depuis le passage précédent : lorsque les allocations moins les destructions font plus que threshold0, un passage est initié. Lors des premiers passages, seule la génération 0 est inspectée. La génération 1 est examinée périodiquement, lorsque le nombre de passages sur la génération 0 depuis le dernier passage ayant aussi examiné la génération 1 vient à excéder threshold1. Les règles pour la génération 2 sont plus complexes. Pour avoir des détails, voir Collecting the oldest generation (dans le guide du développeur, en anglais).
- gc.get_count()¶
Renvoie un triplet des nombres totaux de passages effectués par génération.
- gc.get_threshold()¶
Renvoie les seuils de passage sous la forme du triplet
(threshold0, threshold1, threshold2)
.
- gc.get_referrers(*objs)¶
Renvoie la liste des objets qui contiennent directement une référence à l'un quelconque des arguments. Il est à noter que cette fonction prend uniquement en compte les objets suivis par le ramasse-miettes, ce qui exclut les instances de certains types d'extension qui contiennent bien des références sans pour autant prendre en charge le ramassage des miettes.
La liste renvoyée peut contenir des objets déjà isolés, mais maintenus en mémoire à cause d'un cycle. Pour les exclure, appelez
collect()
juste avantget_referrers()
.Avertissement
La manipulation des objets renvoyés par
get_referrers()
est hasardeuse car ils risquent d'être encore en cours d'initialisation, donc dans un état temporairement instable. Mieux vaut réserverget_referrers()
au débogage.Lève un événement d'audit
gc.get_referrers
avec l'argumentobjs
.
- gc.get_referents(*objs)¶
Renvoie une liste des objets pointés par les références que contiennent les arguments. Ils sont déterminés en appelant, si présente, la méthode C
tp_traverse
de chaque argument, qui visite les objets auxquels cet argument fait référence. Il est à noter quetp_traverse
n'est définie que par les objets qui gèrent le ramassage des miettes, et n'a l'obligation de visiter que les objets qui peuvent potentiellement faire partie d'un cycle. Ainsi, la liste renvoyée par cette fonction ne contient par forcément tous les objets qu'il est possible d'atteindre à partir des arguments. Par exemple, si l'un des arguments contient un entier, ce dernier objet peut être présent ou non dans la liste.Lève un événement d'audit
gc.get_referents
avec l'argumentobjs
.
- gc.is_tracked(obj)¶
Renvoie
True
ouFalse
selon que l'argument est suivi ou non par le ramasse-miettes. En règle générale, les objets atomiques ne sont pas suivis, tandis que les objets non-atomiques, tels que les conteneurs et instances de classes définies par l'utilisateur, le sont. Cependant, certains types présentent des optimisations qui permettent de se passer avantageusement du ramasse-miettes dans les cas simples, comme les dictionnaires dont toutes les clés et valeurs sont atomiques :>>> gc.is_tracked(0) False >>> gc.is_tracked("a") False >>> gc.is_tracked([]) True >>> gc.is_tracked({}) False >>> gc.is_tracked({"a": 1}) False >>> gc.is_tracked({"a": []}) True
Ajouté dans la version 3.1.
- gc.is_finalized(obj)¶
Renvoie
True
ouFalse
selon que l'argument a été finalisé par le ramasse-miettes.>>> 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
Ajouté dans la version 3.9.
- gc.freeze()¶
Freeze all the objects tracked by the garbage collector; move them to a permanent generation and ignore them in all the future collections.
If a process will
fork()
withoutexec()
, avoiding unnecessary copy-on-write in child processes will maximize memory sharing and reduce overall memory usage. This requires both avoiding creation of freed "holes" in memory pages in the parent process and ensuring that GC collections in child processes won't touch thegc_refs
counter of long-lived objects originating in the parent process. To accomplish both, callgc.disable()
early in the parent process,gc.freeze()
right beforefork()
, andgc.enable()
early in child processes.Ajouté dans la version 3.7.
- gc.unfreeze()¶
Unfreeze the objects in the permanent generation, put them back into the oldest generation.
Ajouté dans la version 3.7.
- gc.get_freeze_count()¶
Return the number of objects in the permanent generation.
Ajouté dans la version 3.7.
Les variables suivantes sont publiques, mais elles ne sont pas censées être modifiées (vous pouvez les muter, mais pas les redéfinir) :
- gc.garbage¶
Liste des objets indestructibles, que le ramasse-miettes n'a pas pu éliminer bien qu'ils soient inatteignables. Depuis Python 3.4, cette liste demeure la plupart du temps vide. Elle peut se remplir si le programme fait appel à des types d'extension définis en C avec un champ
tp_del
différent deNULL
.Si
DEBUG_SAVEALL
est actif, tous les objets inatteignables sont ajoutés à cette liste au lieu d'être détruits.Modifié dans la version 3.2: Si cette liste n'est pas vide lors de l'arrêt de l'interpréteur, un
ResourceWarning
est émis (les avertissements de ce type sont silencieux par défaut). De plus, siDEBUG_UNCOLLECTABLE
est actif, tous les objets indestructibles sont affichés.Modifié dans la version 3.4: Following PEP 442, objects with a
__del__()
method don't end up ingc.garbage
anymore.
- gc.callbacks¶
Liste de fonctions de rappel lancées par le ramasse-miettes avant et après un passage. Elles prennent deux arguments, phase et info.
phase peut prendre deux valeurs :
"start"
lorsque le passage du ramasse-miettes est imminent."stop"
lorsque le passage du ramasse-miettes vient de se terminer.info est un dictionnaire qui donne plus d'informations à la fonction de rappel. Les clés suivantes sont actuellement présentes :
"generation"
, la génération la plus âgée intégrée à ce passage ;"collected"
: si phase vaut"stop"
, le nombre d'objets détruits avec succès ;"uncollectable"
: si phase vaut"stop"
, le nombre d'objets indestructibles ajoutés àgarbage
.Toute application peut ajouter ses propres fonctions de rappel à cette liste. Voici les principales applications :
Faire des statistiques sur le passage du ramasse-miettes, par exemple la fréquence à laquelle chaque génération est examinée, ou bien le temps d'un passage ;
Identifier les types définis par une application dont les instances s'ajoutent à
garbage
car elles sont indestructibles.Ajouté dans la version 3.3.
Les constantes suivantes définissent les options de débogage que l'on peut passer à set_debug()
:
- gc.DEBUG_STATS¶
Affiche des statistiques durant les passages du ramasse-miettes. Utile pour pouvoir régler la fréquence des passages.
- gc.DEBUG_COLLECTABLE¶
Affiche des informations sur les objets détruits.
- gc.DEBUG_UNCOLLECTABLE¶
Affiche des informations sur les objets indestructibles (ceux qui sont ajoutés à la liste
garbage
, qui sont inatteignables mais dont la mémoire ne peut pas être libérée).Modifié dans la version 3.2: Affiche également le contenu de
garbage
à l'arrêt de l'interpréteur, pour peu que cette liste ne soit pas vide.
- gc.DEBUG_SAVEALL¶
Lorsque cette option est active, les objets inatteignables sont ajoutés à la liste garbage au lieu d'être supprimés. Ceci est utile pour déboguer une fuite de mémoire.
- gc.DEBUG_LEAK¶
Combinaison des options utiles au débogage d'une fuite de mémoire. Il s'agit d'un raccourci pour
DEBUG_COLLECTABLE|DEBUG_UNCOLLECTABLE|DEBUG_SAVEALL
.