From 31ee985db86c1339d00bd0d3cc1712019460670a Mon Sep 17 00:00:00 2001
From: Irit Katriel <1055913+iritkatriel@users.noreply.github.com>
Date: Wed, 18 Aug 2021 20:50:19 +0100
Subject: [PATCH] bpo-44874: deprecate Py_TRASHCAN_SAFE_BEGIN and
 Py_TRASHCAN_SAFE_END (GH-27693)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Victor Stinner <vstinner@python.org>
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
---
 Doc/whatsnew/3.11.rst                         | 41 +++++++++++++++++++
 Include/cpython/object.h                      | 17 ++++++--
 .../2021-08-09-19-05-20.bpo-44874.oOcfU4.rst  |  1 +
 3 files changed, 55 insertions(+), 4 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Core and Builtins/2021-08-09-19-05-20.bpo-44874.oOcfU4.rst

diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
index c546ec0fc6d..49b4364be9b 100644
--- a/Doc/whatsnew/3.11.rst
+++ b/Doc/whatsnew/3.11.rst
@@ -307,6 +307,47 @@ New Features
 Porting to Python 3.11
 ----------------------
 
+* The old trashcan macros (``Py_TRASHCAN_SAFE_BEGIN``/``Py_TRASHCAN_SAFE_END``)
+  are now deprecated. They should be replaced by the new macros
+  ``Py_TRASHCAN_BEGIN`` and ``Py_TRASHCAN_END``.
+
+  A tp_dealloc function that has the old macros, such as::
+
+    static void
+    mytype_dealloc(mytype *p)
+    {
+        PyObject_GC_UnTrack(p);
+        Py_TRASHCAN_SAFE_BEGIN(p);
+        ...
+        Py_TRASHCAN_SAFE_END
+    }
+
+  should migrate to the new macros as follows::
+
+    static void
+    mytype_dealloc(mytype *p)
+    {
+        PyObject_GC_UnTrack(p);
+        Py_TRASHCAN_BEGIN(p, mytype_dealloc)
+        ...
+        Py_TRASHCAN_END
+    }
+
+  Note that ``Py_TRASHCAN_BEGIN`` has a second argument which
+  should be the deallocation function it is in.
+
+  To support older Python versions in the same codebase, you
+  can define the following macros and use them throughout
+  the code (credit: these were copied from the ``mypy`` codebase)::
+
+    #if PY_MAJOR_VERSION >= 3 && PY_MINOR_VERSION >= 8
+    #  define CPy_TRASHCAN_BEGIN(op, dealloc) Py_TRASHCAN_BEGIN(op, dealloc)
+    #  define CPy_TRASHCAN_END(op) Py_TRASHCAN_END
+    #else
+    #  define CPy_TRASHCAN_BEGIN(op, dealloc) Py_TRASHCAN_SAFE_BEGIN(op)
+    #  define CPy_TRASHCAN_END(op) Py_TRASHCAN_SAFE_END(op)
+    #endif
+
 * The :c:func:`PyType_Ready` function now raises an error if a type is defined
   with the :const:`Py_TPFLAGS_HAVE_GC` flag set but has no traverse function
   (:c:member:`PyTypeObject.tp_traverse`).
diff --git a/Include/cpython/object.h b/Include/cpython/object.h
index 75cd0f90022..5ae6f367c60 100644
--- a/Include/cpython/object.h
+++ b/Include/cpython/object.h
@@ -534,7 +534,16 @@ PyAPI_FUNC(int) _PyTrash_cond(PyObject *op, destructor dealloc);
     Py_TRASHCAN_BEGIN_CONDITION(op, \
         _PyTrash_cond(_PyObject_CAST(op), (destructor)dealloc))
 
-/* For backwards compatibility, these macros enable the trashcan
- * unconditionally */
-#define Py_TRASHCAN_SAFE_BEGIN(op) Py_TRASHCAN_BEGIN_CONDITION(op, 1)
-#define Py_TRASHCAN_SAFE_END(op) Py_TRASHCAN_END
+/* The following two macros, Py_TRASHCAN_SAFE_BEGIN and
+ * Py_TRASHCAN_SAFE_END, are deprecated since version 3.11 and
+ * will be removed in the future.
+ * Use Py_TRASHCAN_BEGIN and Py_TRASHCAN_END instead.
+ */
+Py_DEPRECATED(3.11) typedef int UsingDeprecatedTrashcanMacro;
+#define Py_TRASHCAN_SAFE_BEGIN(op) \
+    do { \
+        UsingDeprecatedTrashcanMacro cond=1; \
+        Py_TRASHCAN_BEGIN_CONDITION(op, cond);
+#define Py_TRASHCAN_SAFE_END(op) \
+        Py_TRASHCAN_END; \
+    } while(0);
diff --git a/Misc/NEWS.d/next/Core and Builtins/2021-08-09-19-05-20.bpo-44874.oOcfU4.rst b/Misc/NEWS.d/next/Core and Builtins/2021-08-09-19-05-20.bpo-44874.oOcfU4.rst
new file mode 100644
index 00000000000..1aed5351d74
--- /dev/null
+++ b/Misc/NEWS.d/next/Core and Builtins/2021-08-09-19-05-20.bpo-44874.oOcfU4.rst	
@@ -0,0 +1 @@
+Deprecate the old trashcan macros (``Py_TRASHCAN_SAFE_BEGIN``/``Py_TRASHCAN_SAFE_END``). They should be replaced by the new macros ``Py_TRASHCAN_BEGIN`` and ``Py_TRASHCAN_END``.