From 135af1a54f55ee91c67b44b17ee0a937e3311e7a Mon Sep 17 00:00:00 2001 From: Mark Shannon Date: Wed, 20 Jan 2021 16:23:53 +0000 Subject: [PATCH] PEP 651: Revise C-API (#1772) *Removes Py_CheckStackDepthWithHeadRoom and makes Py_EnterRecursiveCall call Py_CheckStackDepth. --- pep-0651.rst | 34 +++++++++++----------------------- 1 file changed, 11 insertions(+), 23 deletions(-) diff --git a/pep-0651.rst b/pep-0651.rst index f4131cd1e..0ac382dd2 100644 --- a/pep-0651.rst +++ b/pep-0651.rst @@ -116,8 +116,7 @@ then a ``StackOverflow`` exception should be raised. C-API ----- -There will be no C-API for modifying Python recursion depth. -It will be managed internally by the interpreter. +A new function, ``Py_CheckStackDepth()`` will be added, and the behavior of ``Py_EnterRecursiveCall()`` will be modified slightly. Py_CheckStackDepth() '''''''''''''''''''' @@ -126,32 +125,15 @@ Py_CheckStackDepth() will return 0 if there is no immediate danger of C stack overflow. It will return -1 and set an exception, if the C stack is near to overflowing. - -Py_CheckStackDepthWithHeadRoom() -'''''''''''''''''''''''''''''''' - -``int Py_CheckStackDepthWithHeadroom(const char *where, int headroom)`` -Behaves like ``Py_CheckStackDepth(where)`` but reduces the effective stack size -by ``headroom`` bytes when determining the risk of C stack overflow. -This function should be used when additional C stack will be -needed for cleanup. - -``Py_CheckStackDepth(where)`` is equivalent to ``Py_CheckStackDepthWithHeadRoom(where, 0)``. - -Unless absolutely necessary to perform complex cleanup, -authors of extension modules are advised to use ``Py_CheckStackDepth()`` -and return immediately on failure. - Py_EnterRecursiveCall() ''''''''''''''''''''''' -This will become a synonym for Py_CheckStackDepth(). +``Py_EnterRecursiveCall()`` will be modified to call ``Py_CheckStackDepth()`` before performing its current function. PyLeaveRecursiveCall() '''''''''''''''''''''' -This will have no effect. - +``Py_LeaveRecursiveCall()`` will remain unchanged. Backwards Compatibility ======================= @@ -162,9 +144,15 @@ For example, the gdb scripts for Python will need to be aware that there may be per C frame. C code that uses the ``Py_EnterRecursiveCall()``, ``PyLeaveRecursiveCall()`` pair of -functions will continue to work correctly. +functions will continue to work correctly. In addition, ``Py_EnterRecursiveCall()`` +may raise a ``StackOverflow`` exception. + +New code should use the ``Py_CheckStackDepth()`` function, unless the code wants to +count as a Python function call with regard to the recursion limit. + +We recommend that "python-like" code, such as Cython-generated functions, +use ``Py_EnterRecursiveCall()``, but other code use ``Py_CheckStackDepth()``. -New code should use the ``Py_CheckStackDepth()`` function. Security Implications =====================