Merged revisions 78760,78771-78773,78802,78922,78952 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r78760 | georg.brandl | 2010-03-07 16:23:59 +0100 (So, 07 Mär 2010) | 1 line
#5341: more built-in vs builtin fixes.
........
r78771 | georg.brandl | 2010-03-07 21:58:31 +0100 (So, 07 Mär 2010) | 1 line
#8085: The function is called PyObject_NewVar, not PyObject_VarNew.
........
r78772 | georg.brandl | 2010-03-07 22:12:28 +0100 (So, 07 Mär 2010) | 1 line
#8039: document conditional expressions better, giving them their own section.
........
r78773 | georg.brandl | 2010-03-07 22:32:06 +0100 (So, 07 Mär 2010) | 1 line
#8044: document Py_{Enter,Leave}RecursiveCall functions.
........
r78802 | georg.brandl | 2010-03-08 17:28:40 +0100 (Mo, 08 Mär 2010) | 1 line
Fix typo.
........
r78922 | georg.brandl | 2010-03-13 14:41:58 +0100 (Sa, 13 Mär 2010) | 1 line
Update for new download location.
........
r78952 | georg.brandl | 2010-03-14 10:55:08 +0100 (So, 14 Mär 2010) | 1 line
#8137: add iso-8859-16 to the standard encodings table.
........
diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index 5fa35a0..619f0f6 100644
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -471,6 +471,36 @@
This steals a reference to *ctx*.
+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