Contagem de Referência

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

void Py_INCREF(PyObject *o)

Increment the reference count for object o. The object must not be NULL; if you aren’t sure that it isn’t NULL, use Py_XINCREF().

void Py_XINCREF(PyObject *o)

Increment the reference count for object o. The object may be NULL, in which case the macro has no effect.

void Py_DECREF(PyObject *o)

Decrement the reference count for object o. The object must not be NULL; if you aren’t sure that it isn’t NULL, use Py_XDECREF(). If the reference count reaches zero, the object’s type’s deallocation function (which must not be NULL) is invoked.

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)

Decrement the reference count for object o. The object may be NULL, in which case the macro has no effect; otherwise the effect is the same as for Py_DECREF(), and the same warning applies.

void Py_CLEAR(PyObject *o)

Decrement the reference count for object o. The object may be NULL, in which case the macro has no effect; otherwise the effect is the same as for Py_DECREF(), except that the argument is also set to NULL. The warning for Py_DECREF() does not apply with respect to the object passed because the macro carefully uses a temporary variable and sets the argument to NULL before decrementing its reference count.

It is a good idea to use this macro whenever decrementing the value of a variable that might be traversed during garbage collection.

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.