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.
........

3 files changed, 32 insertions, 2 deletions

diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index 5fa35a008f..619f0f6398 100644
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -471,6 +471,36 @@ Exception Objects
    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
diff --git a/Doc/c-api/gcsupport.rst b/Doc/c-api/gcsupport.rst
index 4f4d27d001..1a280c823a 100644
--- a/Doc/c-api/gcsupport.rst
+++ b/Doc/c-api/gcsupport.rst
@@ -28,7 +28,7 @@ include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
 Constructors for container types must conform to two rules:
 
 #. The memory for the object must be allocated using :cfunc:`PyObject_GC_New`
-   or :cfunc:`PyObject_GC_VarNew`.
+   or :cfunc:`PyObject_GC_NewVar`.
 
 #. Once all the fields which may contain references to other containers are
    initialized, it must call :cfunc:`PyObject_GC_Track`.
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 378bfe1d89..eb8a83e179 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -182,7 +182,7 @@ type objects) *must* have the :attr:`ob_size` field.
    instance; this is normally :cfunc:`PyObject_Del` if the instance was allocated
    using :cfunc:`PyObject_New` or :cfunc:`PyObject_VarNew`, or
    :cfunc:`PyObject_GC_Del` if the instance was allocated using
-   :cfunc:`PyObject_GC_New` or :cfunc:`PyObject_GC_VarNew`.
+   :cfunc:`PyObject_GC_New` or :cfunc:`PyObject_GC_NewVar`.
 
    This field is inherited by subtypes.