gc — Interface para o coletor de lixo

---

Este módulo fornece uma interface para o coletor de lixo opcional. Ele disponibiliza a habilidade de desabilitar o coletor, 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 coletor encontra mas não pode “limpar”. Como o coletor complementa a contagem de referência já usada em Python, você pode desabilitar o coletor se você tem certeza que o seu programa não cria ciclos de referência. 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 coletor de lixo 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()

Desabilita a coleta de lixo automática.

gc.isenabled()

Retorna True se a coleta automática estiver habilitada.

gc.collect(generation=2)

Perform a 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.

Calling gc.collect(0) will perform a GC collection on the young generation.

Calling gc.collect(1) will perform a GC collection on the young generation and an increment of the old generation.

Calling gc.collect(2) or gc.collect() performs a full collection

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.

O efeito de chamar gc.collect() enquanto o interpretador já está realizando uma coleta é indefinido.

Alterado na versão 3.13: generation=1 performs an increment of collection.

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

Retorna os sinalizadores de depuração atualmente definidos.

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 as follows:

• 0: All objects in the young generation

• 1: No objects, as there is no generation 1 (as of Python 3.13)

• 2: All objects in the old generation

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

Alterado na versão 3.13: Generation 1 is removed

Levanta um evento de auditoria gc.get_objects com o argumento 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.

Adicionado 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 two generations depending on whether they have survived a collection. New objects are placed in the young generation. If an object survives a collection it is moved into the old generation.

In order to decide when to run, the collector keeps track of the number of object allocations and deallocations since the last collection. When the number of allocations minus the number of deallocations exceeds threshold0, collection starts. For each collection, all the objects in the young generation and some fraction of the old generation is collected.

The fraction of the old generation that is collected is inversely proportional to threshold1. The larger threshold1 is, the slower objects in the old generation are collected. For the default value of 10, 1% of the old generation is scanned during each collection.

threshold2 is ignored.

See Garbage collector design for more information.

Alterado na versão 3.13: threshold2 is ignored

gc.get_count()

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

gc.get_threshold()

Retorna os limites da coleta 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.

Levanta um evento de auditoria gc.get_referrers com o argumento 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.

Levanta um evento de auditoria gc.get_referents com o argumento 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

Adicionado na versão 3.1.

gc.is_finalized(obj)

Retorna True se o objeto fornecido foi finalizado pelo coletor de lixo, False caso contrário.

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

Adicionado na versão 3.9.

gc.freeze()

Congela todos os objetos rastreados pelo coletor de lixo; move-os para uma geração permanente e ignora-os em todas as coleções futuras.

Se um processo for fork() sem exec(), evitar cópia em gravação (copy-on-write) desnecessário em processos filho maximizará o compartilhamento de memória e reduzirá o uso geral de memória. Isso requer evitar a criação de “buracos” liberados nas páginas de memória no processo pai e garantir que as coleções GC nos processos filho não toquem no contador gc_refs de objetos de vida longa originados no processo pai. Para realizar ambos, chame gc.disable() no início do processo pai, gc.freeze() logo antes de fork() e gc.enable() no início em processos filhos.

Adicionado na versão 3.7.

gc.unfreeze()

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

Adicionado na versão 3.7.

gc.get_freeze_count()

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

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

Adicionado 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).