Doc: C API: Move `tp_dealloc` paragraph to `tp_dealloc` section (#125737)

It looks like commit 43cf44ddcc
(gh-31501) accidentally moved the paragraph to the `tp_finalize`
section when the intent was to move it to the `tp_dealloc` section
(according to the commit message).

Also:
  * Convert the paragraph to a warning.
  * Apply the appropriate font style to `tp_dealloc`.
  * Unlinkify the first mention of `tp_dealloc` since the paragraph is
    already in the `tp_dealloc` section.
This commit is contained in:
Richard Hansen 2024-10-21 12:46:37 -04:00 committed by GitHub
parent d67bf2d89a
commit d880c83ff7
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 13 additions and 11 deletions

View File

@ -682,6 +682,19 @@ and :c:data:`PyType_Type` effectively act as defaults.)
Py_DECREF(tp); Py_DECREF(tp);
} }
.. warning::
In a garbage collected Python, :c:member:`!tp_dealloc` may be called from
any Python thread, not just the thread which created the object (if the
object becomes part of a refcount cycle, that cycle might be collected by
a garbage collection on any thread). This is not a problem for Python
API calls, since the thread on which :c:member:`!tp_dealloc` is called
will own the Global Interpreter Lock (GIL). However, if the object being
destroyed in turn destroys objects from some other C or C++ library, care
should be taken to ensure that destroying those objects on the thread
which called :c:member:`!tp_dealloc` will not violate any assumptions of
the library.
**Inheritance:** **Inheritance:**
@ -2109,17 +2122,6 @@ and :c:data:`PyType_Type` effectively act as defaults.)
PyErr_Restore(error_type, error_value, error_traceback); PyErr_Restore(error_type, error_value, error_traceback);
} }
Also, note that, in a garbage collected Python,
:c:member:`~PyTypeObject.tp_dealloc` may be called from
any Python thread, not just the thread which created the object (if the object
becomes part of a refcount cycle, that cycle might be collected by a garbage
collection on any thread). This is not a problem for Python API calls, since
the thread on which tp_dealloc is called will own the Global Interpreter Lock
(GIL). However, if the object being destroyed in turn destroys objects from some
other C or C++ library, care should be taken to ensure that destroying those
objects on the thread which called tp_dealloc will not violate any assumptions
of the library.
**Inheritance:** **Inheritance:**
This field is inherited by subtypes. This field is inherited by subtypes.