"gc" — Interface du ramasse-miettes
***********************************

======================================================================

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" ou "False" selon que le ramasse-miettes est activé
   ou non.

gc.collect(generation=2)

   Déclenche un passage du ramasse-miettes. En l'absence d'argument,
   un passage complet est effectué. Le paramètre *generation* permet
   de le limiter à une génération entre 0 et 2. Une exception
   "ValueError" est levée si le numéro de la génération n'est pas
   valide. Cette fonction renvoie le nombre d'objets inatteignables
   qui ont été détectés.

   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)

   Renvoie la liste des objets suivis par le ramasse-miettes, à
   l'exclusion de cette liste elle-même. Le paramètre facultatif
   *generation* restreint la liste aux objets d'une génération
   particulière.

   Modifié dans la version 3.8: ajout du paramètre *generation*.

   Lève un événement d'audit "gc.get_objects" avec l'argument
   "generation".

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 liste "garbage") au
     sein de cette génération.

   Nouveau 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 avant "get_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éserver "get_referrers()" au débogage.

   Lève un événement d'audit "gc.get_referrers" avec l'argument
   "objs".

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 que
   "tp_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'argument
   "objs".

gc.is_tracked(obj)

   Renvoie "True" ou "False" 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

   Nouveau dans la version 3.1.

gc.is_finalized(obj)

   Renvoie "True" ou "False" 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

   Nouveau 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()" without "exec()", 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 the "gc_refs"
   counter of long-lived objects originating in the parent process. To
   accomplish both, call "gc.disable()" early in the parent process,
   "gc.freeze()" right before "fork()", and "gc.enable()" early in
   child processes.

   Nouveau dans la version 3.7.

gc.unfreeze()

   Unfreeze the objects in the permanent generation, put them back
   into the oldest generation.

   Nouveau dans la version 3.7.

gc.get_freeze_count()

   Return the number of objects in the permanent generation.

   Nouveau 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 de "NULL".

   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, si
   "DEBUG_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 in "gc.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.

   Nouveau 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".
