Conteo de referencias

Las funciónes y macros de esta sección se utilizan para administrar conteos de referencia de objetos en Python.

Py_ssize_t Py_REFCNT(PyObject *o)

Part of the Stable ABI since version 3.14.

Obtiene el recuento de referencias para el objeto de Python o.

Ten cuenta que el valor devuelto puede que no reflejar cúantas referencias al objecto existen realmente. Por ejemplo, algunos objetos son :term:”immortal” y tienen un refcount muy alto que no refleja el número real de referencias. Por lo tanto, no confíes en que el valor devuelto sea presciso, salvo cuando sea 0 o 1.

Usa la función Py_SET_REFCNT() para establecer la cuenta de referencias de un objeto.

Nota

On free threaded builds of Python, returning 1 isn’t sufficient to determine if it’s safe to treat o as having no access by other threads. Use PyUnstable_Object_IsUniquelyReferenced() for that instead.

See also the function PyUnstable_Object_IsUniqueReferencedTemporary().

Distinto en la versión 3.10: Py_REFCNT() se convierte en una función estática en línea.

Distinto en la versión 3.11: El tipo de parámetro ya no es const PyObject*.

void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)

Establece la cuenta de referencias del objeto o al valor refcnt.

En compilación de Python con Free Threading <free-threading-build> `, si *refcnt* es mas mayor que ``UINT32_MAX`, el objeto se convierte en immortal.

Esta función no afecta a los objetos immortal.

Added in version 3.9.

Distinto en la versión 3.12: Los objetos inmortales no se modifican.

void Py_INCREF(PyObject *o)

Indica tomar una nueva strong reference al objeto o, lo que indica que está en uso y no debe ser destruido.

Esta función no afecta a los objetos immortal.

Esta función se usa generalmente para convertir un borrowed reference en un strong reference en su lugar. La función Py_NewRef() se puede utilizar para crear un nuevo strong reference.

Cuando se termine de usar el objeto, se libera llamando a Py_DECREF().

El objeto no debe ser NULL; si no está seguro de que no sea NULL, use Py_XINCREF().

Do not expect this function to actually modify o in any way. For at least some objects, this function has no effect.

Distinto en la versión 3.12: Los objetos inmortales no se modifican.

void Py_XINCREF(PyObject *o)

Similar a Py_INCREF(), pero el objeto o puede ser NULL, en cuyo caso esto no tiene efecto.

Ver también Py_XNewRef().

PyObject *Py_NewRef(PyObject *o)

Part of the Stable ABI since version 3.10.

Crea una nueva strong reference a un objeto: llama a Py_INCREF() sobre o y devuelve el objeto o.

Cuando la strong reference ya no sea necesaria, se debe llamar a Py_DECREF() para disminuir el recuento de referencias del objeto.

El objeto o no debe ser NULL; use Py_XNewRef() si o puede ser NULL.

Por ejemplo:

Py_INCREF(obj);
self->attr = obj;

puede ser escrito como:

self->attr = Py_NewRef(obj);

Ver también Py_INCREF().

Added in version 3.10.

PyObject *Py_XNewRef(PyObject *o)

Part of the Stable ABI since version 3.10.

Similar a Py_NewRef(), pero el objeto o puede ser NULL.

Si el objeto o es NULL, la función solo retorna NULL.

Added in version 3.10.

void Py_DECREF(PyObject *o)

Libera una strong reference al objeto o, indicando que la referencia ya no se usa.

Esta función no afecta a los objetos immortal.

Una vez que la última strong reference sea liberada (por ejemplo, cuando la cuenta de referencias del objeto llegue a 0), se invoca la función de desasignación del tipo de objeto (la cual no debe ser NULL).

Esta función se usa generalmente para eliminar un strong reference antes de salir de su alcance.

El objeto no debe ser NULL; si no está seguro de que no sea NULL, use Py_XINCREF().

Do not expect this function to actually modify o in any way. For at least some objects, this function has no effect.

Advertencia

La función de desasignación puede hacer que se invoque un código arbitrario de Python (por ejemplo, cuando se desasigna una instancia de clase con el método __del__()). Mientras las excepciones en dicho código no sean propagadas, el código ejecutado tendrá acceso libre a todas las variables globales de Python. Esto significa que cualquier objeto al que se pueda acceder desde una variable global debería estar en un estado coherente antes de invocar a Py_DECREF(). Por ejemplo, el código para eliminar un objeto de una lista debe copiar una referencia al objeto eliminado en una variable temporal, actualizar la estructura de datos de la lista y luego llamar a Py_DECREF() para la variable temporal.

Distinto en la versión 3.12: Los objetos inmortales no se modifican.

void Py_XDECREF(PyObject *o)

Similar a Py_DECREF(), pero el objeto o puede ser NULL, en cuyo caso esto no tendría efecto alguno. El mismo aviso de Py_DECREF() aplica aqui también.

void Py_CLEAR(PyObject *o)

Libera una strong reference del objeto o. El objeto puede ser NULL, en cuyo caso el macro no tiene efecto; de lo contrario, el efecto es el mismo que el de Py_DECREF(), excepto que el argumento también se establece en NULL. La advertencia de Py_DECREF() no se aplica en este caso, ya que el macro usa cuidadosamente una variable temporal y asigna NULL al algumento antes de luberar la referencia

Es buena idea usar este macro al liberar una referencia de un objeto que podría ser recorrido durante la recolección de basura.

Distinto en la versión 3.12: Ahora, el macro argumento solo se evalua una vez. Si el argumento tiene efectos secundarios, estos ya no se duplican.

void Py_IncRef(PyObject *o)

Part of the Stable ABI.

Indica la toma de una nueva strong reference al objeto o. Es una versión en forma de función de Py_XINCREF(). Puede utilizarse para la integración dinámica de Python en tiempo de ejecución.

void Py_DecRef(PyObject *o)

Part of the Stable ABI.

Libera una strong reference al objeto o. Una versión en forma de función de Py_XDECREF(). Puede utilizarse para la integración dinámica de Python en tiempo de ejecución.

Py_SETREF(dst, src)

Un macro que libera de forma segura un strong reference al objeto dst y establece dst al valor src.

Como en el caso de Py_CLEAR(), el codigo «obvio» puede ser mortal:

Py_DECREF(dst);
dst = src;

La forma segura es:

Py_SETREF(dst, src);

Eso termina asignando dst al valor src _antes de_ liberar la referencia al valor anterior de dst, para que cualquier código ejecutado como efecto secundario de dst siendo destruido ya no crea que dst señala a un objeto válido.

Added in version 3.6.

Distinto en la versión 3.12: Los macro argumentos ahora solo se evalúan una vez. Si algún argumento tiene efectos secundarios, estos ya no se duplican.

Py_XSETREF(dst, src)

Un variante del macro Py_SETREF que usa Py_XDECREF() en lugar de Py_DECREF().

Added in version 3.6.

Distinto en la versión 3.12: Los macro argumentos ahora solo se evalúan una vez. Si algún argumento tiene efectos secundarios, estos ya no se duplican.