#8044: document Py_{Enter,Leave}RecursiveCall functions.

1 files changed, 30 insertions, 0 deletions

diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index 474478c..d4a13ae 100644
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -454,6 +454,36 @@ is a separate error indicator for each thread.
    the warning message.
 
 
+Recursion Control
+=================
+
+These two functions provide a way to perform safe recursive calls at the C
+level, both in the core and in extension modules.  They are needed if the
+recursive code does not necessarily invoke Python code (which tracks its
+recursion depth automatically).
+
+.. cfunction:: int Py_EnterRecursiveCall(char *where)
+
+   Marks a point where a recursive C-level call is about to be performed.
+
+   If :const:`USE_STACKCHECK` is defined, this function checks if the the OS
+   stack overflowed using :cfunc:`PyOS_CheckStack`.  In this is the case, it
+   sets a :exc:`MemoryError` and returns a nonzero value.
+
+   The function then checks if the recursion limit is reached.  If this is the
+   case, a :exc:`RuntimeError` is set and a nonzero value is returned.
+   Otherwise, zero is returned.
+
+   *where* should be a string such as ``" in instance check"`` to be
+   concatenated to the :exc:`RuntimeError` message caused by the recursion depth
+   limit.
+
+.. cfunction:: void Py_LeaveRecursiveCall()
+
+   Ends a :cfunc:`Py_EnterRecursiveCall`.  Must be called once for each
+   *successful* invocation of :cfunc:`Py_EnterRecursiveCall`.
+
+
 .. _standardexceptions:
 
 Standard Exceptions