diff options
| -rw-r--r-- | Doc/ACKS.txt | 1 | ||||
| -rw-r--r-- | Doc/c-api/init.rst | 48 | ||||
| -rw-r--r-- | Doc/c-api/utilities.rst | 49 | ||||
| -rw-r--r-- | Doc/c-api/veryhigh.rst | 37 | ||||
| -rw-r--r-- | Doc/extending/extending.rst | 23 |
5 files changed, 153 insertions, 5 deletions
diff --git a/Doc/ACKS.txt b/Doc/ACKS.txt index 804a77d..c41007b 100644 --- a/Doc/ACKS.txt +++ b/Doc/ACKS.txt @@ -162,6 +162,7 @@ docs@python.org), and we'll be glad to correct the problem. * Justin Sheehy * Michael Simcich * Ionel Simionescu +* Michael Sloan * Gregory P. Smith * Roy Smith * Clay Spence 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() diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst index 4a11d97..21eeddf 100644 --- a/Doc/extending/extending.rst +++ b/Doc/extending/extending.rst @@ -471,10 +471,10 @@ Later, when it is time to call the function, you call the C function :cfunc:`PyEval_CallObject`. This function has two arguments, both pointers to arbitrary Python objects: the Python function, and the argument list. The argument list must always be a tuple object, whose length is the number of -arguments. To call the Python function with no arguments, pass an empty tuple; -to call it with one argument, pass a singleton tuple. :cfunc:`Py_BuildValue` -returns a tuple when its format string consists of zero or more format codes -between parentheses. For example:: +arguments. To call the Python function with no arguments, pass in NULL, or +an empty tuple; to call it with one argument, pass a singleton tuple. +:cfunc:`Py_BuildValue` returns a tuple when its format string consists of zero +or more format codes between parentheses. For example:: int arg; PyObject *arglist; @@ -532,9 +532,22 @@ event code, you might use the following code:: Py_DECREF(result); Note the placement of ``Py_DECREF(arglist)`` immediately after the call, before -the error check! Also note that strictly spoken this code is not complete: +the error check! Also note that strictly speaking this code is not complete: :cfunc:`Py_BuildValue` may run out of memory, and this should be checked. +You may also call a function with keyword arguments by using +:cfunc:`PyEval_CallObjectWithKeywords`. As in the above example, we use +:cfunc:`Py_BuildValue` to construct the dictionary. :: + + PyObject *dict; + ... + dict = Py_BuildValue("{s:i}", "name", val); + result = PyEval_CallObjectWithKeywords(my_callback, NULL, dict); + Py_DECREF(dict); + if (result == NULL) + return NULL; /* Pass error back */ + /* Here maybe use the result */ + Py_DECREF(result); .. _parsetuple: |