diff options
Diffstat (limited to 'Doc/c-api/object.rst')
| -rw-r--r-- | Doc/c-api/object.rst | 18 |
1 files changed, 18 insertions, 0 deletions
diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index efad4d215b1..0fd159f1eb8 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -737,3 +737,21 @@ Object Protocol caller must hold a :term:`strong reference` to *obj* when calling this. .. versionadded:: 3.14 + +.. c:function:: int PyUnstable_Object_IsUniquelyReferenced(PyObject *op) + + Determine if *op* only has one reference. + + On GIL-enabled builds, this function is equivalent to + :c:expr:`Py_REFCNT(op) == 1`. + + On a :term:`free threaded <free threading>` build, this checks if *op*'s + :term:`reference count` is equal to one and additionally checks if *op* + is only used by this thread. :c:expr:`Py_REFCNT(op) == 1` is **not** + thread-safe on free threaded builds; prefer this function. + + The caller must hold an :term:`attached thread state`, despite the fact + that this function doesn't call into the Python interpreter. This function + cannot fail. + + .. versionadded:: 3.14 |