summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
authorGeorg Brandl <georg@python.org>2010-03-07 21:32:06 (GMT)
committerGeorg Brandl <georg@python.org>2010-03-07 21:32:06 (GMT)
commit0d4bfec13420ff5085c80dca2fe94cdb90712018 (patch)
tree61d2c3b1eeca1bde721190f0b830de7f1d0a50e9 /Doc
parent38c72030db4206e27340dc5a0f489a0f7a103f81 (diff)
downloadcpython-0d4bfec13420ff5085c80dca2fe94cdb90712018.zip
cpython-0d4bfec13420ff5085c80dca2fe94cdb90712018.tar.gz
cpython-0d4bfec13420ff5085c80dca2fe94cdb90712018.tar.bz2
#8044: document Py_{Enter,Leave}RecursiveCall functions.
Diffstat (limited to 'Doc')
-rw-r--r--Doc/c-api/exceptions.rst30
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