# `gc` — Interface para o coletor de lixo

Este módulo fornece uma interface para o opcional garbage collector. Ele disponibiliza a habilidade de desabilitar o collector, ajustar a frequência da coleção, e configurar as opções de depuração. Ele também fornece acesso para objetos inacessíveis que o collector encontra mas não pode “limpar”. Como o collector complementa a contagem de referência já usada em Python, você pode desabilitar o collector se você tem certeza que o seu programa não cria ciclos de referências. A coleta automática pode ser desabilitada pela chamada `gc.disable()`. Para depurar um programa vazando, chame `gc.set_debug(gc.DEBUG_LEAK)`. Perceba que isto inclui `gc.DEBUG_SAVEALL`, fazendo com que objetos coletados pelo garbage-collector sejam salvos para inspeção em gc.garbage.

O módulo `gc` fornece as seguintes funções:

`gc.``enable`()

  Habilita a coleta de lixo automática.

`gc.``disable`()

  Desative a coleta de lixo automática.

`gc.``isenabled`()

  Retorne `True` se a coleta automática estiver habilitada.

`gc.``collect`(generation=2)

  Sem argumentos, execute uma coleta completa. O argumento opcional generation pode ser um inteiro especificando qual geração coletar (de 0 a 2). Uma exceção `ValueError` é levantada se o número de geração for inválido. O número de objetos inacessíveis encontrados é retornado.

  As listas livres mantidas para vários tipos embutidos são limpas sempre que uma coleta completa ou coleta da geração mais alta (2) é executada. Nem todos os itens em algumas listas livres podem ser liberados devido à implementação particular, em particular `float`.

`gc.``set_debug`(flags)

  Define os sinalizadores de depuração da coleta de lixo. As informações de depuração serão gravadas em `sys.stderr`. Veja abaixo uma lista de sinalizadores de depuração que podem ser combinados usando operações de bit para controlar a depuração.

`gc.``get_debug`()

  Retorne os sinalizadores de depuração atualmente definidos.

`gc.``get_objects`(generation=None)

  Retorna uma lista de todos os objetos rastreados pelo coletor, excluindo a lista retornada. Se generation não for None, retorna apenas os objetos rastreados pelo coletor que estão nessa geração.

  Alterado na versão 3.8: Novo parâmetro generation

  Raises an auditing event `gc.get_objects` with argument `generation`.

`gc.``get_stats`()

  Retorna uma lista de três dicionários por geração contendo estatísticas de coleta desde o início do interpretador. O número de chaves pode mudar no futuro, mas atualmente cada dicionário conterá os seguintes itens:

  - ``collections``é o número de vezes que esta geração foi coletada;

  - `collected` é o número total de objetos coletados nesta geração;

  - `uncollectable` é o número total de objetos que foram considerados incobráveis (e, portanto, movidos para a lista `garbage`) dentro desta geração.

  Novo na versão 3.4.

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

  Define os limites de coleta de lixo (a frequência de coleta). Definir threshold0 como zero desativa a coleta.

  The GC classifies objects into three generations depending on how many collection sweeps they have survived. New objects are placed in the youngest generation (generation `0`). If an object survives a collection it is moved into the next older generation. Since generation `2` is the oldest generation, objects in that generation remain there after a collection. In order to decide when to run, the collector keeps track of the number object allocations and deallocations since the last collection. When the number of allocations minus the number of deallocations exceeds threshold0, collection starts. Initially only generation `0` is examined. If generation `0` has been examined more than threshold1 times since generation `1` has been examined, then generation `1` is examined as well. With the third generation, things are a bit more complicated, see Collecting the oldest generation for more information.

`gc.``get_count`()

  Retorna as contagens da coleta atual como uma tupla de `(count0, count1, count2)`.

`gc.``get_threshold`()

  Retorne os limites da coleção atual como uma tupla de `(threshold0, threshold1, threshold2)`.

`gc.``get_referrers`(*objs)

  Retorna a lista de objetos que se referem diretamente a qualquer um dos objs. Esta função localizará apenas os contêineres que suportam coleta de lixo; tipos de extensão que se referem a outros objetos, mas não suportam coleta de lixo, não serão encontrados.

  Observe que os objetos que já foram desreferenciados, mas que vivem em ciclos e ainda não foram coletados pelo coletor de lixo podem ser listados entre os referenciadores resultantes. Para obter apenas os objetos atualmente ativos, chame `collect()` antes de chamar `get_referrers()`.

  Aviso

  Deve-se tomar cuidado ao usar objetos retornados por `get_referrers()` porque alguns deles ainda podem estar em construção e, portanto, em um estado temporariamente inválido. Evite usar `get_referrers()` para qualquer finalidade que não seja depuração.

  Raises an auditing event `gc.get_referrers` with argument `objs`.

`gc.``get_referents`(*objs)

  Retorna uma lista de objetos diretamente referenciados por qualquer um dos argumentos. Os referentes retornados são aqueles objetos visitados pelos métodos a nível do C `tp_traverse` dos argumentos (se houver), e podem não ser todos os objetos diretamente alcançáveis. Os métodos `tp_traverse` são suportados apenas por objetos que suportam coleta de lixo e são necessários apenas para visitar objetos que possam estar envolvidos em um ciclo. Assim, por exemplo, se um número inteiro pode ser acessado diretamente de um argumento, esse objeto inteiro pode ou não aparecer na lista de resultados.

  Raises an auditing event `gc.get_referents` with argument `objs`.

`gc.``is_tracked`(obj)

  Retorna `True` se o objeto está atualmente rastreado pelo coletor de lixo, `False` caso contrário. Como regra geral, as instâncias de tipos atômicos não são rastreadas e as instâncias de tipos não atômicos (contêineres, objetos definidos pelo usuário…) são. No entanto, algumas otimizações específicas do tipo podem estar presentes para suprimir a pegada do coletor de lixo de instâncias simples (por exemplo, dicts contendo apenas chaves e 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

  Novo na versão 3.1.

`gc.``freeze`()

  Freeze all the objects tracked by gc - move them to a permanent generation and ignore all the future collections. This can be used before a POSIX fork() call to make the gc copy-on-write friendly or to speed up collection. Also collection before a POSIX fork() call may free pages for future allocation which can cause copy-on-write too so it’s advised to disable gc in parent process and freeze before fork and enable gc in child process.

  Novo na versão 3.7.

`gc.``unfreeze`()

  Descongela os objetos na geração permanente, coloca-os de volta na geração mais antiga.

  Novo na versão 3.7.

`gc.``get_freeze_count`()

  Retorna o número de objetos na geração permanente.

  Novo na versão 3.7.

As seguintes variáveis são fornecidas para acesso somente leitura (você pode alterar os valores, mas não deve revinculá-los):

`gc.``garbage`

  Uma lista de objetos que o coletor considerou inacessíveis, mas não puderam ser liberados (objetos não coletáveis). A partir do Python 3.4, esta lista deve estar vazia na maioria das vezes, exceto ao usar instâncias de tipos de extensão C com um slot `tp_del` não-`NULL`.

  Se `DEBUG_SAVEALL` for definido, todos os objetos inacessíveis serão adicionados a esta lista ao invés de liberados.

  Alterado na versão 3.2: Se esta lista não estiver vazia no desligamento do interpretador, um `ResourceWarning` é emitido, que é silencioso por padrão. Se `DEBUG_UNCOLLECTABLE` for definido, além disso, todos os objetos não coletáveis serão impressos.

  Alterado na versão 3.4: Seguindo a PEP 442, objetos com um método `__del__()` não vão mais para `gc.garbage`.

`gc.``callbacks`

  Uma lista de retornos de chamada que serão invocados pelo coletor de lixo antes e depois da coleta. As funções de retorno serão chamadas com dois argumentos, phase e info.

  phase pode ser um dos dois valores:

  > “start”: A coleta de lixo está prestes a começar.

  > “stop”: A coleta de lixo terminou.

  info é um ditado que fornece mais informações para a função de retorno. As seguintes chaves estão atualmente definidas:

  > “generation”: A geração mais antiga sendo coletada.

  > “collected”: Quando phase é “stop”, o número de objetos coletados com sucesso.

  > “uncollectable”: Quando phase é “stop”, o número de objetos que não puderam ser coletados e foram colocados em `garbage`.

  As aplicações podem adicionar suas próprias funções de retorno a essa lista. Os principais casos de uso são:

  > Reunir estatísticas sobre coleta de lixo, como com que frequência várias gerações são coletadas e quanto tempo leva a coleta.

  > Permitindo que os aplicativos identifiquem e limpem seus próprios tipos não colecionáveis quando eles aparecem em `garbage`.

  Novo na versão 3.3.

As seguintes constantes são fornecidas para uso com `set_debug()`:

`gc.``DEBUG_STATS`

  Imprimir estatísticas durante a coleta. Esta informação pode ser útil ao sintonizar a frequência de coleta.

`gc.``DEBUG_COLLECTABLE`

  Imprimir informações sobre objetos colecionáveis encontrados.

`gc.``DEBUG_UNCOLLECTABLE`

  Imprime informações de objetos não colecionáveis encontrados (objetos que não são alcançáveis, mas não podem ser liberados pelo coletor). Esses objetos serão adicionados à lista `garbage`.

  Alterado na versão 3.2: Imprime também o conteúdo da lista `garbage` em desligamento do interpretador, se não estiver vazia.

`gc.``DEBUG_SAVEALL`

  Quando definido, todos os objetos inacessíveis encontrados serão anexados ao lixo em vez de serem liberados. Isso pode ser útil para depurar um programa com vazamento.

`gc.``DEBUG_LEAK`

  Os sinalizadores de depuração necessários para o coletor imprimir informações sobre um programa com vazamento (igual a `DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | DEBUG_SAVEALL`).