[Python-checkins] r78773 - python/trunk/Doc/c-api/exceptions.rst

Sun Mar 7 22:32:06 CET 2010

Author: georg.brandl
Date: Sun Mar 7 22:32:06 2010
New Revision: 78773
Log:
#8044: document Py_{Enter,Leave}RecursiveCall functions.
Modified:
 python/trunk/Doc/c-api/exceptions.rst
Modified: python/trunk/Doc/c-api/exceptions.rst
==============================================================================

--- python/trunk/Doc/c-api/exceptions.rst	(original)
+++ python/trunk/Doc/c-api/exceptions.rst	Sun Mar 7 22:32:06 2010
@@ -454,6 +454,36 @@
 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
