From: Richard Hansen <rhansen@rhansen.org>
Date: Mon, 21 Oct 2024 16:46:37 +0000 (-0400)
Subject: Doc: C API: Move `tp_dealloc` paragraph to `tp_dealloc` section (#125737)
X-Git-Tag: v3.14.0a2~346
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=d880c83ff7fb2e464bc4f469d74cc3fc3eca082c;p=thirdparty%2FPython%2Fcpython.git

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.
---

diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index da1b5092fbf7..0c59b3da0795 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.