From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Mon, 21 Oct 2024 16:55:11 +0000 (+0200)
Subject: [3.12] Doc: C API: Move `tp_dealloc` paragraph to `tp_dealloc` section (GH-125737... 
X-Git-Tag: v3.12.8~181
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=c3e705fbe5258d8d02f2e405d04b72c427bb4a74;p=thirdparty%2FPython%2Fcpython.git

[3.12] Doc: C API: Move `tp_dealloc` paragraph to `tp_dealloc` section (GH-125737) (#125799)

Doc: C API: Move `tp_dealloc` paragraph to `tp_dealloc` section (GH-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).

(cherry picked from commit d880c83ff7fb2e464bc4f469d74cc3fc3eca082c)

Co-authored-by: Richard Hansen <rhansen@rhansen.org>
---

diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 1b28a2a3060e..610cb96e8885 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -704,6 +704,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:**
 
@@ -2101,17 +2114,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.