From d880c83ff7fb2e464bc4f469d74cc3fc3eca082c Mon Sep 17 00:00:00 2001 From: Richard Hansen Date: Mon, 21 Oct 2024 12:46:37 -0400 Subject: [PATCH] Doc: C API: Move `tp_dealloc` paragraph to `tp_dealloc` section (#125737) It looks like commit 43cf44ddcce6b225f959ea2a53e4817244ca6054 (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. --- Doc/c-api/typeobj.rst | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index da1b5092fbf..0c59b3da079 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -682,6 +682,19 @@ and :c:data:`PyType_Type` effectively act as defaults.) 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:** @@ -2109,17 +2122,6 @@ and :c:data:`PyType_Type` effectively act as defaults.) 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:** This field is inherited by subtypes.