"gc" --- Interfaz del recolector de basura
******************************************

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

Este módulo proporciona una interfaz para el recolector de basura
opcional (recolector de basura cíclico generacional). Proporciona la
capacidad de deshabilitar el recolector, ajustar la frecuencia de
recolección y establecer opciones de depuración. También proporciona
acceso a objetos inaccesibles (*unreachables*) que el recolector
encontró pero no pudo liberar. Dado que el recolector de basura
complementa el conteo de referencias, que ya se utiliza en Python, es
posible desactivarlo siempre que se esté seguro de que el programa no
crea referencias cíclicas. La recolección automática se puede
desactivar llamando a "gc.disable()". Para depurar un programa con
fugas de memoria, se debe llamar a "gc.set_debug(gc.DEBUG_LEAK)". Se
debe tener en cuenta que la llamada anterior incluye
"gc.DEBUG_SAVEALL", lo que hace que los objetos recolectados se
guarden en *gc.garbage* para su inspección.

El módulo "gc" proporciona las siguientes funciones:

gc.enable()

   Habilita la recolección automática de basura.

gc.disable()

   Deshabilita la recolección automática de basura.

gc.isenabled()

   Retorna "True" si la recolección automática está habilitada.

gc.collect(generation=2)

   Sin argumentos, ejecuta una recolección completa. El argumento
   opcional *generation* debe ser un número entero que especifica qué
   generación recolectar (de 0 a 2). Una excepción "ValueError" será
   lanzada si el número de generación no es válido. Se retorna el
   número de objetos inaccesibles encontrados.

   Las listas libres mantenidas para varios tipos incorporados son
   borradas cada vez que se ejecuta una recolección completa o una
   recolección de la generación más alta (2). No obstante, no todos
   los elementos de algunas listas libres pueden ser liberados,
   particularmente "float", debido a su implementación particular.

gc.set_debug(flags)

   Establece las flags de depuración para la recolección de basura. La
   información de depuración se escribirá en "sys.stderr". A
   continuación se puede consultar una lista con las flags de
   depuración disponibles, que se pueden combinar mediante operaciones
   de bits para controlar la depuración.

gc.get_debug()

   Retorna las flags de depuración actualmente establecidas.

gc.get_objects(generation=None)

   Retorna una lista de todos los objetos rastreados por el
   recolector, excluyendo la lista retornada. Si *generation* no es
   "None", retorna solo los objetos rastreados por el recolector que
   pertenecen a esa generación.

   Distinto en la versión 3.8: Se agregó el parámetro *generation*.

   Lanza un evento de auditoría "gc.get_objects" con el argumento
   "generation".

gc.get_stats()

   Retorna una lista de tres diccionarios, uno por cada generación,
   que contienen estadísticas de recolección desde el inicio del
   intérprete. El número de claves puede cambiar en el futuro, pero
   actualmente cada diccionario contendrá los siguientes elementos:

   * "collections" es el número de veces que se recolectó esta
     generación;

   * "collected" es el número total de objetos recolectados dentro de
     esta generación;

   * "uncollectable" es el número total de objetos que se consideraron
     no recolectables (y por lo tanto, se movieron a la lista
     "garbage") dentro de esta generación.

   Nuevo en la versión 3.4.

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

   Establece los umbrales de recolección (la frecuencia de
   recolección). Si se establece *threshold0* en cero se deshabilita
   la recolección.

   El recolector de basura (GC por sus siglas en inglés) clasifica los
   objetos en tres generaciones dependiendo de cuántos barridos de
   colección hayan sobrevivido. Los nuevos objetos se colocan en la
   generación más joven (generación "0"). Si un objeto sobrevive a una
   colección, se traslada a la siguiente generación anterior. Dado que
   la generación "2" es la generación más antigua, los objetos de esa
   generación permanecen allí después de una colección. Para decidir
   cuándo ejecutar, el recopilador realiza un seguimiento del número
   de asignaciones y desasignaciones de objetos desde la última
   recopilación. Cuando el número de asignaciones menos el número de
   desasignaciones supera el *treshold0*, comienza la recopilación.
   Inicialmente solo se examina la generación "0". Si la generación
   "0" se ha examinado más de *treshold1* veces desde que se examinó
   la generación "1", también se examina la generación "1". Con la
   tercera generación, las cosas son un poco más complicadas, consulte
   Recopilación de la generación más antigua para obtener más
   información.

gc.get_count()

   Retorna los recuentos de la recolección actual como una tupla de la
   forma "(count0, count1, count2)".

gc.get_threshold()

   Retorna los umbrales de la recolección actual como una tupla de la
   forma "(threshold0, threshold1, threshold2)".

gc.get_referrers(*objs)

   Retorna la lista de objetos que referencian de forma directa a
   cualquiera de *objs*. Esta función solo localizará aquellos
   contenedores que admitan la recolección de basura; no se
   localizarán los tipos de extensión que referencian a otros objetos
   pero que no admiten la recolección de basura.

   Téngase en cuenta que los objetos que ya se han desreferenciado,
   pero que tienen referencias cíclicas y aún no han sido recolectados
   por el recolector de basura pueden enumerarse entre las referencias
   resultantes. Para obtener solo los objetos activos actualmente,
   llame a "collect()" antes de llamar a "get_referrers()".

   Advertencia:

     Se debe tener un especial cuidado cuando se usan objetos
     retornados por "get_referrers()" dado que algunos de ellos aún
     podrían estar en construcción y por tanto en un estado
     temporalmente inválido. Debe evitarse el uso de "get_referrers()"
     para cualquier propósito que no sea la depuración.

   Lanza un evento de auditoría "gc.get_referrers" con el argumento
   "objs".

gc.get_referents(*objs)

   Retorna una lista de objetos a los que hace referencia directamente
   cualquiera de los argumentos. Las referencias retornadas son
   aquellos objetos visitados por los métodos "tp_traverse" a nivel de
   C de los argumentos (si los hay) y es posible que no todos los
   objetos sean directamente accesibles realmente. Los métodos
   "tp_traverse" solo son compatibles con los objetos que admiten
   recolección de basura y solo se requieren para visitar objetos que
   pueden estar involucrados en un ciclo de referencias. Lo que quiere
   decir que, por ejemplo, si se puede acceder directamente a un
   número entero desde uno de los argumento, ese objeto entero puede
   aparecer o no en la lista de resultados.

   Lanza un evento de auditoría "gc.get_referents" con el argumento
   "objs".

gc.is_tracked(obj)

   Retorna "True" si el recolector de basura rastrea actualmente el
   objeto y "False" en caso contrario. Como regla general, las
   instancias de tipos atómicos no se rastrean y las instancias de
   tipos no atómicos (contenedores, objetos definidos por el usuario
   ...) sí. Sin embargo, algunas optimizaciones específicas de tipo
   pueden estar presentes para suprimir el impacto del recolector de
   basura en instancias simples (por ejemplo, diccionarios que
   contienen solo claves y valores atómicos):

      >>> 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

   Nuevo en la versión 3.1.

gc.is_finalized(obj)

   Retorna "True" si el objeto dado ha sido finalizado por el
   recolector de basura, "False" en caso contrario.

      >>> 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

   Nuevo en la versión 3.9.

gc.freeze()

   Congela todos los objetos rastreados por el recolector de basura -
   los mueve a una generación permanente e ignora todas las
   recolecciones futuras. Esto se puede usar antes de una llamada a
   *fork()* de POSIX para hacer el recolector de basura amigable con
   *copy-on-write* ("copiar al escribir") o para acelerar la
   recolección. Además, la recolección antes de una llamada *fork()*
   de POSIX puede liberar páginas para futuras asignaciones, lo que
   también puede causar *copy-on-write*, por lo que se recomienda
   deshabilitar el recolector de basura en el proceso principal,
   congelar antes de la bifurcación y habilitarlo posteriormente en el
   proceso secundario.

   Nuevo en la versión 3.7.

gc.unfreeze()

   Descongela los objetos de la generación permanente y vuelve a
   colocarlos en la generación más antigua.

   Nuevo en la versión 3.7.

gc.get_freeze_count()

   Retorna el número de objetos de la generación permanente.

   Nuevo en la versión 3.7.

Las siguientes variables se proporcionan para acceso de solo lectura
(se pueden mutar los valores pero no se deben vincular de nuevo):

gc.garbage

   Una lista de objetos que el recolector consideró inaccesibles pero
   que no pudieron ser liberados (objetos que no se pueden
   recolectar). A partir de Python 3.4, esta lista debe estar vacía la
   mayor parte del tiempo, excepto cuando se utilizan instancias de
   tipos de extensión C en los que la ranura (*slot*) "tp_del" no sea
   "NULL".

   Si se establece "DEBUG_SAVEALL", todos los objetos inaccesibles se
   agregarán a esta lista en lugar de ser liberados.

   Distinto en la versión 3.2: Si la lista no está vacía en el momento
   del *interpreter shutdown*, se emite un "ResourceWarning", que es
   silencioso de forma predeterminada. Si se establece
   "DEBUG_UNCOLLECTABLE", además se imprimen todos los objetos no
   recolectables.

   Distinto en la versión 3.4: Cumpliendo con **PEP 442**, los objetos
   con un método "__del__()" ya no terminan en "gc.garbage".

gc.callbacks

   Una lista de retrollamadas que el recolector de basura invocará
   antes y después de la recolección. Las retrollamadas serán llamadas
   con dos argumentos, *phase* e *info*.

   *phase* puede tomar uno de estos valores:

      "start": la recolección de basura está a punto de comenzar.

      "stop": la recolección de basura ha terminado.

   *info* es un diccionario que proporciona información adicional para
   la retrollamada. Las siguientes claves están definidas actualmente:

      "generation": la generación más antigua que ha sido recolectada.

      "collected": cuando *phase* es "stop", el número de objetos
      recolectados satisfactoriamente.

      "uncollectable": cuando *phase* es "stop", el número de objetos
      que no pudieron ser recolectados y fueron ubicados en "garbage".

   Las aplicaciones pueden agregar sus propias retrollamadas a esta
   lista. Los principales casos de uso son:

      Recopilar estadísticas sobre la recolección de basura, como la
      frecuencia con la que se recolectan varias generaciones y cuánto
      tiempo lleva la recolección.

      Permitir que las aplicaciones identifiquen y borren sus propios
      tipos no recolectables cuando aparecen en "garbage".

   Nuevo en la versión 3.3.

Las siguientes constantes son proporcionadas para ser usadas con
"set_debug()":

gc.DEBUG_STATS

   Imprime estadísticas durante la recolección. Esta información puede
   resultar útil para ajustar la frecuencia de recolección.

gc.DEBUG_COLLECTABLE

   Imprime información sobre los objetos recolectables encontrados.

gc.DEBUG_UNCOLLECTABLE

   Imprime información sobre los objetos no recolectables encontrados
   (objetos inaccesibles, pero que el recolector no puede liberar).
   Estos objetos se agregarán a la lista "garbage".

   Distinto en la versión 3.2: También imprime el contenido de la
   lista "garbage" durante *interpreter shutdown*, si no está vacía.

gc.DEBUG_SAVEALL

   Cuando se establece, todos los objetos inaccesibles encontrados se
   agregarán a *garbage* en lugar de ser liberados. Esto puede
   resultar útil para depurar un programa con fugas de memoria.

gc.DEBUG_LEAK

   Las flags de depuración necesarias para que el recolector imprima
   información sobre un programa con fugas de memoria (igual a
   "DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | DEBUG_SAVEALL").
