Document PyEval_* functions from ceval.c.

Credits to Michael Sloan from GHOP.

3 files changed, 134 insertions, 0 deletions

diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index 2509e0b..8dd9a57 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -621,6 +621,14 @@ supports the creation of additional interpreters (using
    deadlock ensues.  (This function is available even when thread support is
    disabled at compile time.)
 
+
+.. cfunction:: void PyEval_ReInitThreads()
+
+   This function is called from :cfunc:`PyOS_AfterFork` to ensure that newly
+   created child processes don't hold locks referring to threads which
+   are not running in the child process.
+
+
 The following macros are normally used without a trailing semicolon; look for
 example usage in the Python source distribution.
 
@@ -892,6 +900,46 @@ in previous versions.
    :cfunc:`PyEval_SetProfile`, except the tracing function does receive line-number
    events.
 
+.. cfunction:: PyObject* PyEval_GetCallStats(PyObject *self)
+
+   Return a tuple of function call counts.  There are constants defined for the
+   positions within the tuple:
+   
+   +-------------------------------+-------+
+   | Name                          | Value |
+   +===============================+=======+
+   | :const:`PCALL_ALL`            | 0     |
+   +-------------------------------+-------+
+   | :const:`PCALL_FUNCTION`       | 1     |
+   +-------------------------------+-------+
+   | :const:`PCALL_FAST_FUNCTION`  | 2     |
+   +-------------------------------+-------+
+   | :const:`PCALL_FASTER_FUNCTION`| 3     |
+   +-------------------------------+-------+
+   | :const:`PCALL_METHOD`         | 4     |
+   +-------------------------------+-------+
+   | :const:`PCALL_BOUND_METHOD`   | 5     |
+   +-------------------------------+-------+
+   | :const:`PCALL_CFUNCTION`      | 6     |
+   +-------------------------------+-------+
+   | :const:`PCALL_TYPE`           | 7     |
+   +-------------------------------+-------+
+   | :const:`PCALL_GENERATOR`      | 8     |
+   +-------------------------------+-------+
+   | :const:`PCALL_OTHER`          | 9     |
+   +-------------------------------+-------+
+   | :const:`PCALL_POP`            | 10    |
+   +-------------------------------+-------+
+   
+   :const:`PCALL_FAST_FUNCTION` means no argument tuple needs to be created.
+   :const:`PCALL_FASTER_FUNCTION` means that the fast-path frame setup code is used.
+
+   If there is a method call where the call can be optimized by changing
+   the argument tuple and calling the function directly, it gets recorded
+   twice.
+
+   This function is only present if Python is compiled with :const:`CALL_PROFILE`
+   defined.
 
 .. _advanced-debugging:
 
diff --git a/Doc/c-api/utilities.rst b/Doc/c-api/utilities.rst
index 2a86dcb..bcd84b3 100644
--- a/Doc/c-api/utilities.rst
+++ b/Doc/c-api/utilities.rst
@@ -1015,3 +1015,52 @@ The following functions provide locale-independent string to number conversions.
 
    See the Unix man page :manpage:`atof(2)` for details.
 
+
+.. _reflection:
+
+Reflection
+==========
+
+.. cfunction:: PyObject* PyEval_GetBuiltins()
+
+   Return a dictionary of the builtins in the current execution frame,
+   or the interpreter of the thread state if no frame is currently executing.
+
+
+.. cfunction:: PyObject* PyEval_GetLocals()
+
+   Return a dictionary of the local variables in the current execution frame,
+   or *NULL* if no frame is currently executing.
+   
+
+.. cfunction:: PyObject* PyEval_GetGlobals()
+
+   Return a dictionary of the global variables in the current execution frame,
+   or *NULL* if no frame is currently executing.
+
+
+.. cfunction:: PyFrameObject* PyEval_GetFrame()
+
+   Return the current thread state's frame, which is *NULL* if no frame is
+   currently executing.
+
+
+.. cfunction:: int PyEval_GetRestricted()
+
+   If there is a current frame and it is executing in restricted mode, return true,
+   otherwise false.
+
+
+.. cfunction:: const char* PyEval_GetFuncName(PyObject *func)
+
+   Return the name of *func* if it is a function, class or instance object, else the
+   name of *func*\s type.
+
+
+.. cfunction:: const char* PyEval_GetFuncDesc(PyObject *func)
+
+   Return a description string, depending on the type of *func*.
+   Return values include "()" for functions and methods, " constructor",
+   " instance", and " object".  Concatenated with the result of
+   :cfunc:`PyEval_GetFuncName`, the result will be a description of
+   *func*.
diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst
index 4b26da6..6a3f91d 100644
--- a/Doc/c-api/veryhigh.rst
+++ b/Doc/c-api/veryhigh.rst
@@ -229,6 +229,43 @@ the same library that the Python runtime is using.
    be parsed or compiled.
 
 
+.. cfunction:: PyObject* PyEval_EvalCode(PyCodeObject *co, PyObject *globals, PyObject *locals)
+
+   This is a simplified interface to :cfunc:`PyEval_EvalCodeEx`, with just
+   the code object, and the dictionaries of global and local variables.
+   The other arguments are set to *NULL*.
+
+
+.. cfunction:: PyObject* PyEval_EvalCodeEx(PyCodeObject *co, PyObject *globals, PyObject *locals, PyObject **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *closure)
+
+   Evaluate a precompiled code object, given a particular environment for its
+   evaluation.  This environment consists of dictionaries of global and local
+   variables, arrays of arguments, keywords and defaults, and a closure tuple of
+   cells.
+
+
+.. cfunction:: PyObject* PyEval_EvalFrame(PyFrameObject *f)
+
+   Evaluate an execution frame.  This is a simplified interface to
+   PyEval_EvalFrameEx, for backward compatibility.
+
+
+.. cfunction:: PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)
+
+   This is the main, unvarnished function of Python interpretation.  It is
+   literally 2000 lines long.  The code object associated with the execution
+   frame *f* is executed, interpreting bytecode and executing calls as needed.
+   The additional *throwflag* parameter can mostly be ignored - if true, then
+   it causes an exception to immediately be thrown; this is used for the
+   :meth:`throw` methods of generator objects.
+
+
+.. cfunction:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)
+
+   This function changes the flags of the current evaluation frame, and returns
+   true on success, false on failure.
+
+
 .. cvar:: int Py_eval_input
 
    .. index:: single: Py_CompileString()