\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 supportmulti-threaded Python programs, there's a global lock that must beheld by the current thread before it can safely access Python objects.Without the lock, even the simplest operations could cause problems ina multi-threaded program: for example, when two threads simultaneouslyincrement the reference count of the same object, the reference countcould end up being incremented only once instead of twice. Therefore, the rule exists that only the thread that has acquired theglobal interpreter lock may operate on Python objects or call Python/CAPI functions.  In order to support multi-threaded Python programs,the interpreter regularly releases and reacquires the lock --- bydefault, every 100 bytecode instructions (this can be changed with\withsubitem{(in module sys)}{\ttindex{setcheckinterval()}}\function{sys.setcheckinterval()}).  The lock is also released andreacquired around potentially blocking I/O operations like reading orwriting a file, so that other threads can run while the thread thatrequests the I/O is waiting for the I/O operation to complete. The Python interpreter needs to keep some bookkeeping informationseparate per thread --- for this it uses a data structure called\ctype{PyThreadState}\ttindex{PyThreadState}.  There's one globalvariable, however: the pointer to the current\ctype{PyThreadState}\ttindex{PyThreadState} structure.  While mostthread packages have a way to store ``per-thread global data,''Python's internal platform independent thread abstraction doesn'tsupport this yet.  Therefore, the current thread state must bemanipulated explicitly. This is easy enough in most cases.  Most code manipulating the globalinterpreter 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 macrosis that when Python is compiled without thread support, they aredefined empty, thus saving the thread state and lock manipulations. When thread support is enabled, the block above expands to thefollowing 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 effectas 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()} savesand restores the value of the  global variable\cdata{errno}\ttindex{errno}, since the lock manipulation does notguarantee that \cdata{errno} is left alone.  Also, when thread supportis disabled,\cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} and\cfunction{PyEval_RestoreThread()} don't manipulate the lock; in thiscase, \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} and\cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()} are notavailable.  This is done so that dynamically loaded extensionscompiled with thread support enabled can be loaded by an interpreterthat was compiled with disabled thread support. The global interpreter lock is used to protect the pointer to thecurrent thread state.  When releasing the lock and saving the threadstate, the current thread state pointer must be retrieved before thelock is released (since another thread could immediately acquire thelock 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 whenthreads are created from C, they don't have the global interpreterlock, nor is there a thread state data structure for them.  Suchthreads must bootstrap themselves into existence, by first creating athread state data structure, then acquiring the lock, and finallystoring their thread state pointer, before they can start using thePython/C API.  When they are done, they should reset the thread statepointer, release the lock, and finally free their thread state datastructure. Beginning with version 2.3, threads can now take advantage of the \cfunction{PyGILState_*()} functions to do all of the aboveautomatically.  The typical idiom for calling into Python from a Cthread 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 isonly one global interpreter (created automatically by\cfunction{Py_Initialize()}).  Python still supports the creation ofadditional interpreters (using \cfunction{Py_NewInterpreter()}), butmixing multiple interpreters and the \cfunction{PyGILState_*()} API isunsupported. \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,

Lines 1–500 of 884. Load more