[Python-checkins] bpo-44874: deprecate Py_TRASHCAN_SAFE_BEGIN and Py_TRASHCAN_SAFE_END (GH-27693)

ambv webhook-mailer at python.org
Wed Aug 18 15:50:27 EDT 2021


https://github.com/python/cpython/commit/31ee985db86c1339d00bd0d3cc1712019460670a
commit: 31ee985db86c1339d00bd0d3cc1712019460670a
branch: main
author: Irit Katriel <1055913+iritkatriel at users.noreply.github.com>
committer: ambv <lukasz at langa.pl>
date: 2021-08-18T21:50:19+02:00
summary:

bpo-44874: deprecate Py_TRASHCAN_SAFE_BEGIN and Py_TRASHCAN_SAFE_END (GH-27693)

Co-authored-by: Victor Stinner <vstinner at python.org>
Co-authored-by: Łukasz Langa <lukasz at langa.pl>

files:
A Misc/NEWS.d/next/Core and Builtins/2021-08-09-19-05-20.bpo-44874.oOcfU4.rst
M Doc/whatsnew/3.11.rst
M Include/cpython/object.h

diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
index c546ec0fc6d9b4..49b4364be9bd7f 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 75cd0f9002215b..5ae6f367c6048a 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 00000000000000..1aed5351d74173
--- /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``.



More information about the Python-checkins mailing list