diff options
Diffstat (limited to 'Doc/api/init.tex')
| -rw-r--r-- | Doc/api/init.tex | 884 |
1 files changed, 0 insertions, 884 deletions
diff --git a/Doc/api/init.tex b/Doc/api/init.tex deleted file mode 100644 index 76fcf61430..0000000000 --- a/Doc/api/init.tex +++ /dev/null @@ -1,884 +0,0 @@ -\chapter{Initialization, Finalization, and Threads - \label{initialization}} - -\begin{cfuncdesc}{void}{Py_Initialize}{} - Initialize the Python interpreter. In an application embedding - Python, this should be called before using any other Python/C API - functions; with the exception of - \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()}, - \cfunction{PyEval_InitThreads()}\ttindex{PyEval_InitThreads()}, - \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()}, - and \cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()}. - This initializes the table of loaded modules (\code{sys.modules}), - and\withsubitem{(in module sys)}{\ttindex{modules}\ttindex{path}} - creates the fundamental modules - \module{__builtin__}\refbimodindex{__builtin__}, - \module{__main__}\refbimodindex{__main__} and - \module{sys}\refbimodindex{sys}. It also initializes the module - search\indexiii{module}{search}{path} path (\code{sys.path}). - It does not set \code{sys.argv}; use - \cfunction{PySys_SetArgv()}\ttindex{PySys_SetArgv()} for that. This - is a no-op when called for a second time (without calling - \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} first). There is - no return value; it is a fatal error if the initialization fails. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{Py_InitializeEx}{int initsigs} - This function works like \cfunction{Py_Initialize()} if - \var{initsigs} is 1. If \var{initsigs} is 0, it skips - initialization registration of signal handlers, which - might be useful when Python is embedded. \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_IsInitialized}{} - Return true (nonzero) when the Python interpreter has been - initialized, false (zero) if not. After \cfunction{Py_Finalize()} - is called, this returns false until \cfunction{Py_Initialize()} is - called again. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{Py_Finalize}{} - Undo all initializations made by \cfunction{Py_Initialize()} and - subsequent use of Python/C API functions, and destroy all - sub-interpreters (see \cfunction{Py_NewInterpreter()} below) that - were created and not yet destroyed since the last call to - \cfunction{Py_Initialize()}. Ideally, this frees all memory - allocated by the Python interpreter. This is a no-op when called - for a second time (without calling \cfunction{Py_Initialize()} again - first). There is no return value; errors during finalization are - ignored. - - This function is provided for a number of reasons. An embedding - application might want to restart Python without having to restart - the application itself. An application that has loaded the Python - interpreter from a dynamically loadable library (or DLL) might want - to free all memory allocated by Python before unloading the - DLL. During a hunt for memory leaks in an application a developer - might want to free all memory allocated by Python before exiting - from the application. - - \strong{Bugs and caveats:} The destruction of modules and objects in - modules is done in random order; this may cause destructors - (\method{__del__()} methods) to fail when they depend on other - objects (even functions) or modules. Dynamically loaded extension - modules loaded by Python are not unloaded. Small amounts of memory - allocated by the Python interpreter may not be freed (if you find a - leak, please report it). Memory tied up in circular references - between objects is not freed. Some memory allocated by extension - modules may not be freed. Some extensions may not work properly if - their initialization routine is called more than once; this can - happen if an application calls \cfunction{Py_Initialize()} and - \cfunction{Py_Finalize()} more than once. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyThreadState*}{Py_NewInterpreter}{} - Create a new sub-interpreter. This is an (almost) totally separate - environment for the execution of Python code. In particular, the - new interpreter has separate, independent versions of all imported - modules, including the fundamental modules - \module{__builtin__}\refbimodindex{__builtin__}, - \module{__main__}\refbimodindex{__main__} and - \module{sys}\refbimodindex{sys}. The table of loaded modules - (\code{sys.modules}) and the module search path (\code{sys.path}) - are also separate. The new environment has no \code{sys.argv} - variable. It has new standard I/O stream file objects - \code{sys.stdin}, \code{sys.stdout} and \code{sys.stderr} (however - these refer to the same underlying \ctype{FILE} structures in the C - library). - \withsubitem{(in module sys)}{ - \ttindex{stdout}\ttindex{stderr}\ttindex{stdin}} - - The return value points to the first thread state created in the new - sub-interpreter. This thread state is made in the current thread - state. Note that no actual thread is created; see the discussion of - thread states below. If creation of the new interpreter is - unsuccessful, \NULL{} is returned; no exception is set since the - exception state is stored in the current thread state and there may - not be a current thread state. (Like all other Python/C API - functions, the global interpreter lock must be held before calling - this function and is still held when it returns; however, unlike - most other Python/C API functions, there needn't be a current thread - state on entry.) - - Extension modules are shared between (sub-)interpreters as follows: - the first time a particular extension is imported, it is initialized - normally, and a (shallow) copy of its module's dictionary is - squirreled away. When the same extension is imported by another - (sub-)interpreter, a new module is initialized and filled with the - contents of this copy; the extension's \code{init} function is not - called. Note that this is different from what happens when an - extension is imported after the interpreter has been completely - re-initialized by calling - \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and - \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}; in that case, - the extension's \code{init\var{module}} function \emph{is} called - again. - - \strong{Bugs and caveats:} Because sub-interpreters (and the main - interpreter) are part of the same process, the insulation between - them isn't perfect --- for example, using low-level file operations - like \withsubitem{(in module os)}{\ttindex{close()}} - \function{os.close()} they can (accidentally or maliciously) affect - each other's open files. Because of the way extensions are shared - between (sub-)interpreters, some extensions may not work properly; - this is especially likely when the extension makes use of (static) - global variables, or when the extension manipulates its module's - dictionary after its initialization. It is possible to insert - objects created in one sub-interpreter into a namespace of another - sub-interpreter; this should be done with great care to avoid - sharing user-defined functions, methods, instances or classes - between sub-interpreters, since import operations executed by such - objects may affect the wrong (sub-)interpreter's dictionary of - loaded modules. (XXX This is a hard-to-fix bug that will be - addressed in a future release.) - - Also note that the use of this functionality is incompatible with - extension modules such as PyObjC and ctypes that use the - \cfunction{PyGILState_*} APIs (and this is inherent in the way the - \cfunction{PyGILState_*} functions work). Simple things may work, - but confusing behavior will always be near. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate} - Destroy the (sub-)interpreter represented by the given thread state. - The given thread state must be the current thread state. See the - discussion of thread states below. When the call returns, the - current thread state is \NULL. All thread states associated with - this interpreter are destroyed. (The global interpreter lock must - be held before calling this function and is still held when it - returns.) \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} will - destroy all sub-interpreters that haven't been explicitly destroyed - at that point. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{Py_SetProgramName}{char *name} - This function should be called before - \cfunction{Py_Initialize()}\ttindex{Py_Initialize()} is called - for the first time, if it is called at all. It tells the - interpreter the value of the \code{argv[0]} argument to the - \cfunction{main()}\ttindex{main()} function of the program. This is - used by \cfunction{Py_GetPath()}\ttindex{Py_GetPath()} and some - other functions below to find the Python run-time libraries relative - to the interpreter executable. The default value is - \code{'python'}. The argument should point to a zero-terminated - character string in static storage whose contents will not change - for the duration of the program's execution. No code in the Python - interpreter will change the contents of this storage. -\end{cfuncdesc} - -\begin{cfuncdesc}{char*}{Py_GetProgramName}{} - Return the program name set with - \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()}, or the - default. The returned string points into static storage; the caller - should not modify its value. -\end{cfuncdesc} - -\begin{cfuncdesc}{char*}{Py_GetPrefix}{} - Return the \emph{prefix} for installed platform-independent files. - This is derived through a number of complicated rules from the - program name set with \cfunction{Py_SetProgramName()} and some - environment variables; for example, if the program name is - \code{'/usr/local/bin/python'}, the prefix is \code{'/usr/local'}. - The returned string points into static storage; the caller should - not modify its value. This corresponds to the \makevar{prefix} - variable in the top-level \file{Makefile} and the - \longprogramopt{prefix} argument to the \program{configure} script - at build time. The value is available to Python code as - \code{sys.prefix}. It is only useful on \UNIX{}. See also the next - function. -\end{cfuncdesc} - -\begin{cfuncdesc}{char*}{Py_GetExecPrefix}{} - Return the \emph{exec-prefix} for installed - platform-\emph{de}pendent files. This is derived through a number - of complicated rules from the program name set with - \cfunction{Py_SetProgramName()} and some environment variables; for - example, if the program name is \code{'/usr/local/bin/python'}, the - exec-prefix is \code{'/usr/local'}. The returned string points into - static storage; the caller should not modify its value. This - corresponds to the \makevar{exec_prefix} variable in the top-level - \file{Makefile} and the \longprogramopt{exec-prefix} argument to the - \program{configure} script at build time. The value is available - to Python code as \code{sys.exec_prefix}. It is only useful on - \UNIX. - - Background: The exec-prefix differs from the prefix when platform - dependent files (such as executables and shared libraries) are - installed in a different directory tree. In a typical installation, - platform dependent files may be installed in the - \file{/usr/local/plat} subtree while platform independent may be - installed in \file{/usr/local}. - - Generally speaking, a platform is a combination of hardware and - software families, e.g. Sparc machines running the Solaris 2.x - operating system are considered the same platform, but Intel - machines running Solaris 2.x are another platform, and Intel - machines running Linux are yet another platform. Different major - revisions of the same operating system generally also form different - platforms. Non-\UNIX{} operating systems are a different story; the - installation strategies on those systems are so different that the - prefix and exec-prefix are meaningless, and set to the empty string. - Note that compiled Python bytecode files are platform independent - (but not independent from the Python version by which they were - compiled!). - - System administrators will know how to configure the \program{mount} - or \program{automount} programs to share \file{/usr/local} between - platforms while having \file{/usr/local/plat} be a different - filesystem for each platform. -\end{cfuncdesc} - -\begin{cfuncdesc}{char*}{Py_GetProgramFullPath}{} - Return the full program name of the Python executable; this is - computed as a side-effect of deriving the default module search path - from the program name (set by - \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()} above). - The returned string points into static storage; the caller should - not modify its value. The value is available to Python code as - \code{sys.executable}. - \withsubitem{(in module sys)}{\ttindex{executable}} -\end{cfuncdesc} - -\begin{cfuncdesc}{char*}{Py_GetPath}{} - \indexiii{module}{search}{path} - Return the default module search path; this is computed from the - program name (set by \cfunction{Py_SetProgramName()} above) and some - environment variables. The returned string consists of a series of - directory names separated by a platform dependent delimiter - character. The delimiter character is \character{:} on \UNIX{} and Mac OS X, - \character{;} on Windows. The returned string points into - static storage; the caller should not modify its value. The value - is available to Python code as the list - \code{sys.path}\withsubitem{(in module sys)}{\ttindex{path}}, which - may be modified to change the future search path for loaded - modules. - - % XXX should give the exact rules -\end{cfuncdesc} - -\begin{cfuncdesc}{const char*}{Py_GetVersion}{} - Return the version of this Python interpreter. This is a string - that looks something like - -\begin{verbatim} -"1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]" -\end{verbatim} - - The first word (up to the first space character) is the current - Python version; the first three characters are the major and minor - version separated by a period. The returned string points into - static storage; the caller should not modify its value. The value - is available to Python code as \code{sys.version}. - \withsubitem{(in module sys)}{\ttindex{version}} -\end{cfuncdesc} - -\begin{cfuncdesc}{const char*}{Py_GetBuildNumber}{} - Return a string representing the Subversion revision that this Python - executable was built from. This number is a string because it may contain a - trailing 'M' if Python was built from a mixed revision source tree. - \versionadded{2.5} -\end{cfuncdesc} - -\begin{cfuncdesc}{const char*}{Py_GetPlatform}{} - Return the platform identifier for the current platform. On \UNIX, - this is formed from the ``official'' name of the operating system, - converted to lower case, followed by the major revision number; - e.g., for Solaris 2.x, which is also known as SunOS 5.x, the value - is \code{'sunos5'}. On Mac OS X, it is \code{'darwin'}. On Windows, - it is \code{'win'}. The returned string points into static storage; - the caller should not modify its value. The value is available to - Python code as \code{sys.platform}. - \withsubitem{(in module sys)}{\ttindex{platform}} -\end{cfuncdesc} - -\begin{cfuncdesc}{const char*}{Py_GetCopyright}{} - Return the official copyright string for the current Python version, - for example - - \code{'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'} - - The returned string points into static storage; the caller should - not modify its value. The value is available to Python code as - \code{sys.copyright}. - \withsubitem{(in module sys)}{\ttindex{copyright}} -\end{cfuncdesc} - -\begin{cfuncdesc}{const char*}{Py_GetCompiler}{} - Return an indication of the compiler used to build the current - Python version, in square brackets, for example: - -\begin{verbatim} -"[GCC 2.7.2.2]" -\end{verbatim} - - The returned string points into static storage; the caller should - not modify its value. The value is available to Python code as part - of the variable \code{sys.version}. - \withsubitem{(in module sys)}{\ttindex{version}} -\end{cfuncdesc} - -\begin{cfuncdesc}{const char*}{Py_GetBuildInfo}{} - Return information about the sequence number and build date and time - of the current Python interpreter instance, for example - -\begin{verbatim} -"#67, Aug 1 1997, 22:34:28" -\end{verbatim} - - The returned string points into static storage; the caller should - not modify its value. The value is available to Python code as part - of the variable \code{sys.version}. - \withsubitem{(in module sys)}{\ttindex{version}} -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PySys_SetArgv}{int argc, char **argv} - Set \code{sys.argv} based on \var{argc} and \var{argv}. These - parameters are similar to those passed to the program's - \cfunction{main()}\ttindex{main()} function with the difference that - the first entry should refer to the script file to be executed - rather than the executable hosting the Python interpreter. If there - isn't a script that will be run, the first entry in \var{argv} can - be an empty string. If this function fails to initialize - \code{sys.argv}, a fatal condition is signalled using - \cfunction{Py_FatalError()}\ttindex{Py_FatalError()}. - \withsubitem{(in module sys)}{\ttindex{argv}} - % XXX impl. doesn't seem consistent in allowing 0/NULL for the params; - % check w/ Guido. -\end{cfuncdesc} - -% XXX Other PySys thingies (doesn't really belong in this chapter) - -\section{Thread State and the Global Interpreter Lock - \label{threads}} - -\index{global interpreter lock} -\index{interpreter lock} -\index{lock, interpreter} - -The Python interpreter is not fully thread safe. In order to support -multi-threaded Python programs, there's a global lock that must be -held by the current thread before it can safely access Python objects. -Without the lock, even the simplest operations could cause problems in -a multi-threaded program: for example, when two threads simultaneously -increment the reference count of the same object, the reference count -could end up being incremented only once instead of twice. - -Therefore, the rule exists that only the thread that has acquired the -global interpreter lock may operate on Python objects or call Python/C -API functions. In order to support multi-threaded Python programs, -the interpreter regularly releases and reacquires the lock --- by -default, every 100 bytecode instructions (this can be changed with -\withsubitem{(in module sys)}{\ttindex{setcheckinterval()}} -\function{sys.setcheckinterval()}). The lock is also released and -reacquired around potentially blocking I/O operations like reading or -writing a file, so that other threads can run while the thread that -requests the I/O is waiting for the I/O operation to complete. - -The Python interpreter needs to keep some bookkeeping information -separate per thread --- for this it uses a data structure called -\ctype{PyThreadState}\ttindex{PyThreadState}. There's one global -variable, however: the pointer to the current -\ctype{PyThreadState}\ttindex{PyThreadState} structure. While most -thread packages have a way to store ``per-thread global data,'' -Python's internal platform independent thread abstraction doesn't -support this yet. Therefore, the current thread state must be -manipulated explicitly. - -This is easy enough in most cases. Most code manipulating the global -interpreter lock has the following simple structure: - -\begin{verbatim} -Save the thread state in a local variable. -Release the interpreter lock. -...Do some blocking I/O operation... -Reacquire the interpreter lock. -Restore the thread state from the local variable. -\end{verbatim} - -This is so common that a pair of macros exists to simplify it: - -\begin{verbatim} -Py_BEGIN_ALLOW_THREADS -...Do some blocking I/O operation... -Py_END_ALLOW_THREADS -\end{verbatim} - -The -\csimplemacro{Py_BEGIN_ALLOW_THREADS}\ttindex{Py_BEGIN_ALLOW_THREADS} -macro opens a new block and declares a hidden local variable; the -\csimplemacro{Py_END_ALLOW_THREADS}\ttindex{Py_END_ALLOW_THREADS} -macro closes the block. Another advantage of using these two macros -is that when Python is compiled without thread support, they are -defined empty, thus saving the thread state and lock manipulations. - -When thread support is enabled, the block above expands to the -following code: - -\begin{verbatim} - PyThreadState *_save; - - _save = PyEval_SaveThread(); - ...Do some blocking I/O operation... - PyEval_RestoreThread(_save); -\end{verbatim} - -Using even lower level primitives, we can get roughly the same effect -as follows: - -\begin{verbatim} - PyThreadState *_save; - - _save = PyThreadState_Swap(NULL); - PyEval_ReleaseLock(); - ...Do some blocking I/O operation... - PyEval_AcquireLock(); - PyThreadState_Swap(_save); -\end{verbatim} - -There are some subtle differences; in particular, -\cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()} saves -and restores the value of the global variable -\cdata{errno}\ttindex{errno}, since the lock manipulation does not -guarantee that \cdata{errno} is left alone. Also, when thread support -is disabled, -\cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} and -\cfunction{PyEval_RestoreThread()} don't manipulate the lock; in this -case, \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} and -\cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()} are not -available. This is done so that dynamically loaded extensions -compiled with thread support enabled can be loaded by an interpreter -that was compiled with disabled thread support. - -The global interpreter lock is used to protect the pointer to the -current thread state. When releasing the lock and saving the thread -state, the current thread state pointer must be retrieved before the -lock is released (since another thread could immediately acquire the -lock and store its own thread state in the global variable). -Conversely, when acquiring the lock and restoring the thread state, -the lock must be acquired before storing the thread state pointer. - -Why am I going on with so much detail about this? Because when -threads are created from C, they don't have the global interpreter -lock, nor is there a thread state data structure for them. Such -threads must bootstrap themselves into existence, by first creating a -thread state data structure, then acquiring the lock, and finally -storing their thread state pointer, before they can start using the -Python/C API. When they are done, they should reset the thread state -pointer, release the lock, and finally free their thread state data -structure. - -Beginning with version 2.3, threads can now take advantage of the -\cfunction{PyGILState_*()} functions to do all of the above -automatically. The typical idiom for calling into Python from a C -thread is now: - -\begin{verbatim} - PyGILState_STATE gstate; - gstate = PyGILState_Ensure(); - - /* Perform Python actions here. */ - result = CallSomeFunction(); - /* evaluate result */ - - /* Release the thread. No Python API allowed beyond this point. */ - PyGILState_Release(gstate); -\end{verbatim} - -Note that the \cfunction{PyGILState_*()} functions assume there is -only one global interpreter (created automatically by -\cfunction{Py_Initialize()}). Python still supports the creation of -additional interpreters (using \cfunction{Py_NewInterpreter()}), but -mixing multiple interpreters and the \cfunction{PyGILState_*()} API is -unsupported. - -\begin{ctypedesc}{PyInterpreterState} - This data structure represents the state shared by a number of - cooperating threads. Threads belonging to the same interpreter - share their module administration and a few other internal items. - There are no public members in this structure. - - Threads belonging to different interpreters initially share nothing, - except process state like available memory, open file descriptors - and such. The global interpreter lock is also shared by all - threads, regardless of to which interpreter they belong. -\end{ctypedesc} - -\begin{ctypedesc}{PyThreadState} - This data structure represents the state of a single thread. The - only public data member is \ctype{PyInterpreterState - *}\member{interp}, which points to this thread's interpreter state. -\end{ctypedesc} - -\begin{cfuncdesc}{void}{PyEval_InitThreads}{} - Initialize and acquire the global interpreter lock. It should be - called in the main thread before creating a second thread or - engaging in any other thread operations such as - \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} or - \code{PyEval_ReleaseThread(\var{tstate})}\ttindex{PyEval_ReleaseThread()}. - It is not needed before calling - \cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} or - \cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()}. - - This is a no-op when called for a second time. It is safe to call - this function before calling - \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}. - - When only the main thread exists, no lock operations are needed. - This is a common situation (most Python programs do not use - threads), and the lock operations slow the interpreter down a bit. - Therefore, the lock is not created initially. This situation is - equivalent to having acquired the lock: when there is only a single - thread, all object accesses are safe. Therefore, when this function - initializes the lock, it also acquires it. Before the Python - \module{thread}\refbimodindex{thread} module creates a new thread, - knowing that either it has the lock or the lock hasn't been created - yet, it calls \cfunction{PyEval_InitThreads()}. When this call - returns, it is guaranteed that the lock has been created and that the - calling thread has acquired it. - - It is \strong{not} safe to call this function when it is unknown - which thread (if any) currently has the global interpreter lock. - - This function is not available when thread support is disabled at - compile time. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyEval_ThreadsInitialized}{} - Returns a non-zero value if \cfunction{PyEval_InitThreads()} has been - called. This function can be called without holding the lock, and - therefore can be used to avoid calls to the locking API when running - single-threaded. This function is not available when thread support - is disabled at compile time. \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyEval_AcquireLock}{} - Acquire the global interpreter lock. The lock must have been - created earlier. If this thread already has the lock, a deadlock - ensues. This function is not available when thread support is - disabled at compile time. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyEval_ReleaseLock}{} - Release the global interpreter lock. The lock must have been - created earlier. This function is not available when thread support - is disabled at compile time. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate} - Acquire the global interpreter lock and set the current thread - state to \var{tstate}, which should not be \NULL. The lock must - have been created earlier. If this thread already has the lock, - deadlock ensues. This function is not available when thread support - is disabled at compile time. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate} - Reset the current thread state to \NULL{} and release the global - interpreter lock. The lock must have been created earlier and must - be held by the current thread. The \var{tstate} argument, which - must not be \NULL, is only used to check that it represents the - current thread state --- if it isn't, a fatal error is reported. - This function is not available when thread support is disabled at - compile time. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyThreadState*}{PyEval_SaveThread}{} - Release the interpreter lock (if it has been created and thread - support is enabled) and reset the thread state to \NULL, returning - the previous thread state (which is not \NULL). If the lock has - been created, the current thread must have acquired it. (This - function is available even when thread support is disabled at - compile time.) -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate} - Acquire the interpreter lock (if it has been created and thread - support is enabled) and set the thread state to \var{tstate}, which - must not be \NULL. If the lock has been created, the current thread - must not have acquired it, otherwise deadlock ensues. (This - function is available even when thread support is disabled at - compile time.) -\end{cfuncdesc} - -The following macros are normally used without a trailing semicolon; -look for example usage in the Python source distribution. - -\begin{csimplemacrodesc}{Py_BEGIN_ALLOW_THREADS} - This macro expands to - \samp{\{ PyThreadState *_save; _save = PyEval_SaveThread();}. - Note that it contains an opening brace; it must be matched with a - following \csimplemacro{Py_END_ALLOW_THREADS} macro. See above for - further discussion of this macro. It is a no-op when thread support - is disabled at compile time. -\end{csimplemacrodesc} - -\begin{csimplemacrodesc}{Py_END_ALLOW_THREADS} - This macro expands to \samp{PyEval_RestoreThread(_save); \}}. - Note that it contains a closing brace; it must be matched with an - earlier \csimplemacro{Py_BEGIN_ALLOW_THREADS} macro. See above for - further discussion of this macro. It is a no-op when thread support - is disabled at compile time. -\end{csimplemacrodesc} - -\begin{csimplemacrodesc}{Py_BLOCK_THREADS} - This macro expands to \samp{PyEval_RestoreThread(_save);}: it is - equivalent to \csimplemacro{Py_END_ALLOW_THREADS} without the - closing brace. It is a no-op when thread support is disabled at - compile time. -\end{csimplemacrodesc} - -\begin{csimplemacrodesc}{Py_UNBLOCK_THREADS} - This macro expands to \samp{_save = PyEval_SaveThread();}: it is - equivalent to \csimplemacro{Py_BEGIN_ALLOW_THREADS} without the - opening brace and variable declaration. It is a no-op when thread - support is disabled at compile time. -\end{csimplemacrodesc} - -All of the following functions are only available when thread support -is enabled at compile time, and must be called only when the -interpreter lock has been created. - -\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_New}{} - Create a new interpreter state object. The interpreter lock need - not be held, but may be held if it is necessary to serialize calls - to this function. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp} - Reset all information in an interpreter state object. The - interpreter lock must be held. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp} - Destroy an interpreter state object. The interpreter lock need not - be held. The interpreter state must have been reset with a previous - call to \cfunction{PyInterpreterState_Clear()}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyThreadState*}{PyThreadState_New}{PyInterpreterState *interp} - Create a new thread state object belonging to the given interpreter - object. The interpreter lock need not be held, but may be held if - it is necessary to serialize calls to this function. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate} - Reset all information in a thread state object. The interpreter lock - must be held. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate} - Destroy a thread state object. The interpreter lock need not be - held. The thread state must have been reset with a previous call to - \cfunction{PyThreadState_Clear()}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Get}{} - Return the current thread state. The interpreter lock must be - held. When the current thread state is \NULL, this issues a fatal - error (so that the caller needn't check for \NULL). -\end{cfuncdesc} - -\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Swap}{PyThreadState *tstate} - Swap the current thread state with the thread state given by the - argument \var{tstate}, which may be \NULL. The interpreter lock - must be held. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyThreadState_GetDict}{} - Return a dictionary in which extensions can store thread-specific - state information. Each extension should use a unique key to use to - store state in the dictionary. It is okay to call this function - when no current thread state is available. - If this function returns \NULL, no exception has been raised and the - caller should assume no current thread state is available. - \versionchanged[Previously this could only be called when a current - thread is active, and \NULL{} meant that an exception was raised]{2.3} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyThreadState_SetAsyncExc}{long id, PyObject *exc} - Asynchronously raise an exception in a thread. - The \var{id} argument is the thread id of the target thread; - \var{exc} is the exception object to be raised. - This function does not steal any references to \var{exc}. - To prevent naive misuse, you must write your own C extension - to call this. Must be called with the GIL held. - Returns the number of thread states modified; this is normally one, but - will be zero if the thread id isn't found. If \var{exc} is - \constant{NULL}, the pending exception (if any) for the thread is cleared. - This raises no exceptions. - \versionadded{2.3} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyGILState_STATE}{PyGILState_Ensure}{} -Ensure that the current thread is ready to call the Python C API -regardless of the current state of Python, or of its thread lock. -This may be called as many times as desired by a thread as long as -each call is matched with a call to \cfunction{PyGILState_Release()}. -In general, other thread-related APIs may be used between -\cfunction{PyGILState_Ensure()} and \cfunction{PyGILState_Release()} -calls as long as the thread state is restored to its previous state -before the Release(). For example, normal usage of the -\csimplemacro{Py_BEGIN_ALLOW_THREADS} and -\csimplemacro{Py_END_ALLOW_THREADS} macros is acceptable. - -The return value is an opaque "handle" to the thread state when -\cfunction{PyGILState_Acquire()} was called, and must be passed to -\cfunction{PyGILState_Release()} to ensure Python is left in the same -state. Even though recursive calls are allowed, these handles -\emph{cannot} be shared - each unique call to -\cfunction{PyGILState_Ensure} must save the handle for its call to -\cfunction{PyGILState_Release}. - -When the function returns, the current thread will hold the GIL. -Failure is a fatal error. - \versionadded{2.3} -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyGILState_Release}{PyGILState_STATE} -Release any resources previously acquired. After this call, Python's -state will be the same as it was prior to the corresponding -\cfunction{PyGILState_Ensure} call (but generally this state will be -unknown to the caller, hence the use of the GILState API.) - -Every call to \cfunction{PyGILState_Ensure()} must be matched by a call to -\cfunction{PyGILState_Release()} on the same thread. - \versionadded{2.3} -\end{cfuncdesc} - - -\section{Profiling and Tracing \label{profiling}} - -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - -The Python interpreter provides some low-level support for attaching -profiling and execution tracing facilities. These are used for -profiling, debugging, and coverage analysis tools. - -Starting with Python 2.2, the implementation of this facility was -substantially revised, and an interface from C was added. This C -interface allows the profiling or tracing code to avoid the overhead -of calling through Python-level callable objects, making a direct C -function call instead. The essential attributes of the facility have -not changed; the interface allows trace functions to be installed -per-thread, and the basic events reported to the trace function are -the same as had been reported to the Python-level trace functions in -previous versions. - -\begin{ctypedesc}[Py_tracefunc]{int (*Py_tracefunc)(PyObject *obj, - PyFrameObject *frame, int what, - PyObject *arg)} - The type of the trace function registered using - \cfunction{PyEval_SetProfile()} and \cfunction{PyEval_SetTrace()}. - The first parameter is the object passed to the registration - function as \var{obj}, \var{frame} is the frame object to which the - event pertains, \var{what} is one of the constants - \constant{PyTrace_CALL}, \constant{PyTrace_EXCEPTION}, - \constant{PyTrace_LINE}, \constant{PyTrace_RETURN}, - \constant{PyTrace_C_CALL}, \constant{PyTrace_C_EXCEPTION}, - or \constant{PyTrace_C_RETURN}, and \var{arg} - depends on the value of \var{what}: - - \begin{tableii}{l|l}{constant}{Value of \var{what}}{Meaning of \var{arg}} - \lineii{PyTrace_CALL}{Always \NULL.} - \lineii{PyTrace_EXCEPTION}{Exception information as returned by - \function{sys.exc_info()}.} - \lineii{PyTrace_LINE}{Always \NULL.} - \lineii{PyTrace_RETURN}{Value being returned to the caller.} - \lineii{PyTrace_C_CALL}{Name of function being called.} - \lineii{PyTrace_C_EXCEPTION}{Always \NULL.} - \lineii{PyTrace_C_RETURN}{Always \NULL.} - \end{tableii} -\end{ctypedesc} - -\begin{cvardesc}{int}{PyTrace_CALL} - The value of the \var{what} parameter to a \ctype{Py_tracefunc} - function when a new call to a function or method is being reported, - or a new entry into a generator. Note that the creation of the - iterator for a generator function is not reported as there is no - control transfer to the Python bytecode in the corresponding frame. -\end{cvardesc} - -\begin{cvardesc}{int}{PyTrace_EXCEPTION} - The value of the \var{what} parameter to a \ctype{Py_tracefunc} - function when an exception has been raised. The callback function - is called with this value for \var{what} when after any bytecode is - processed after which the exception becomes set within the frame - being executed. The effect of this is that as exception propagation - causes the Python stack to unwind, the callback is called upon - return to each frame as the exception propagates. Only trace - functions receives these events; they are not needed by the - profiler. -\end{cvardesc} - -\begin{cvardesc}{int}{PyTrace_LINE} - The value passed as the \var{what} parameter to a trace function - (but not a profiling function) when a line-number event is being - reported. -\end{cvardesc} - -\begin{cvardesc}{int}{PyTrace_RETURN} - The value for the \var{what} parameter to \ctype{Py_tracefunc} - functions when a call is returning without propagating an exception. -\end{cvardesc} - -\begin{cvardesc}{int}{PyTrace_C_CALL} - The value for the \var{what} parameter to \ctype{Py_tracefunc} - functions when a C function is about to be called. -\end{cvardesc} - -\begin{cvardesc}{int}{PyTrace_C_EXCEPTION} - The value for the \var{what} parameter to \ctype{Py_tracefunc} - functions when a C function has thrown an exception. -\end{cvardesc} - -\begin{cvardesc}{int}{PyTrace_C_RETURN} - The value for the \var{what} parameter to \ctype{Py_tracefunc} - functions when a C function has returned. -\end{cvardesc} - -\begin{cfuncdesc}{void}{PyEval_SetProfile}{Py_tracefunc func, PyObject *obj} - Set the profiler function to \var{func}. The \var{obj} parameter is - passed to the function as its first parameter, and may be any Python - object, or \NULL. If the profile function needs to maintain state, - using a different value for \var{obj} for each thread provides a - convenient and thread-safe place to store it. The profile function - is called for all monitored events except the line-number events. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyEval_SetTrace}{Py_tracefunc func, PyObject *obj} - Set the tracing function to \var{func}. This is similar to - \cfunction{PyEval_SetProfile()}, except the tracing function does - receive line-number events. -\end{cfuncdesc} - - -\section{Advanced Debugger Support \label{advanced-debugging}} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - -These functions are only intended to be used by advanced debugging -tools. - -\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Head}{} - Return the interpreter state object at the head of the list of all - such objects. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Next}{PyInterpreterState *interp} - Return the next interpreter state object after \var{interp} from the - list of all such objects. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyThreadState *}{PyInterpreterState_ThreadHead}{PyInterpreterState *interp} - Return the a pointer to the first \ctype{PyThreadState} object in - the list of threads associated with the interpreter \var{interp}. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Next}{PyThreadState *tstate} - Return the next thread state object after \var{tstate} from the list - of all such objects belonging to the same \ctype{PyInterpreterState} - object. - \versionadded{2.2} -\end{cfuncdesc} |