Contagem de Referências

As macros nesta seção são usadas para gerenciar contagens de referências de objetos Python.

void Py_INCREF(PyObject *o)

Aumenta a contagem de referências para o objeto o. O objeto não deve ser NULL; se você não tem certeza de que não é NULL, use Py_XINCREF().

void Py_XINCREF(PyObject *o)

Aumenta a contagem de referências para o objeto o. O objeto pode ser NULL, caso em que a macro não tem efeito.

void Py_DECREF(PyObject *o)

Diminui a contagem de referências para o objeto o. O objeto não deve ser NULL; se você não tem certeza de que não é NULL, use Py_XDECREF(). Se a contagem de referências chegar a zero, a função de desalocação do tipo de objeto (que não deve ser NULL) é chamada.

Aviso

A função de desalocação pode fazer com que o código Python arbitrário seja invocado (por exemplo, quando uma instância de classe com um método __del__() é desalocada). Embora as exceções em tal código não sejam propagadas, o código executado tem acesso livre a todas as variáveis globais do Python. Isso significa que qualquer objeto que é alcançável de uma variável global deve estar em um estado consistente antes de Py_DECREF() ser invocado. Por exemplo, o código para excluir um objeto de uma lista deve copiar uma referência ao objeto excluído em uma variável temporária, atualizar a estrutura de dados da lista e então chamar Py_DECREF() para a variável temporária.

void Py_XDECREF(PyObject *o)

Diminui a contagem de referências para o objeto o. O objeto pode ser NULL, caso em que a macro não tem efeito; caso contrário, o efeito é o mesmo de Py_DECREF(), e o mesmo aviso se aplica.

void Py_CLEAR(PyObject *o)

Diminui a contagem de referências para o objeto o. O objeto pode ser NULL, caso em que a macro não tem efeito; caso contrário, o efeito é o mesmo de Py_DECREF(), exceto que o argumento também é definido como NULL. O aviso para Py_DECREF() não se aplica em relação ao objeto passado porque a macro usa cuidadosamente uma variável temporária e define o argumento como NULL antes de diminuir sua contagem de referências.

É uma boa ideia usar essa macro sempre que diminuir a contagem de referências de um objeto que pode ser percorrido durante a coleta de lixo.

As seguintes funções são para incorporação dinâmica de Python em tempo de execução: Py_IncRef(PyObject *o), Py_DecRef(PyObject *o). Elas são simplesmente versões de função exportadas de Py_XINCREF() e Py_XDECREF(), respectivamente.

As seguintes funções ou macros são apenas para uso dentro do núcleo do interpretador: _Py_Dealloc(), _Py_ForgetReference(), _Py_NewReference(), bem como a variável global _Py_RefTotal.