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

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月18日T21: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``.
