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

Co-authored-by: Victor Stinner <vstinner@python.org>
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
This commit is contained in:
Irit Katriel 2021-08-18 20:50:19 +01:00 committed by GitHub
parent a3a4d20d67
commit 31ee985db8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 55 additions and 4 deletions

View File

@ -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`).

View File

@ -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);

View File

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