PEP 651: Revise C-API (#1772)
*Removes Py_CheckStackDepthWithHeadRoom and makes Py_EnterRecursiveCall call Py_CheckStackDepth.
This commit is contained in:
parent
62b03c20a0
commit
135af1a54f
34
pep-0651.rst
34
pep-0651.rst
|
@ -116,8 +116,7 @@ then a ``StackOverflow`` exception should be raised.
|
||||||
C-API
|
C-API
|
||||||
-----
|
-----
|
||||||
|
|
||||||
There will be no C-API for modifying Python recursion depth.
|
A new function, ``Py_CheckStackDepth()`` will be added, and the behavior of ``Py_EnterRecursiveCall()`` will be modified slightly.
|
||||||
It will be managed internally by the interpreter.
|
|
||||||
|
|
||||||
Py_CheckStackDepth()
|
Py_CheckStackDepth()
|
||||||
''''''''''''''''''''
|
''''''''''''''''''''
|
||||||
|
@ -126,32 +125,15 @@ Py_CheckStackDepth()
|
||||||
will return 0 if there is no immediate danger of C stack overflow.
|
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.
|
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()
|
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()
|
PyLeaveRecursiveCall()
|
||||||
''''''''''''''''''''''
|
''''''''''''''''''''''
|
||||||
|
|
||||||
This will have no effect.
|
``Py_LeaveRecursiveCall()`` will remain unchanged.
|
||||||
|
|
||||||
|
|
||||||
Backwards Compatibility
|
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.
|
per C frame.
|
||||||
|
|
||||||
C code that uses the ``Py_EnterRecursiveCall()``, ``PyLeaveRecursiveCall()`` pair of
|
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
|
Security Implications
|
||||||
=====================
|
=====================
|
||||||
|
|
Loading…
Reference in New Issue