cpython-lru_cache-weakref: Doc/api/init.tex annotate

annotate Doc/api/init.tex @ 24042:63fbbed10714 legacy-trunk

Simplify HTTPSConnection constructor. See discussion in SF bug 458463.

author	Jeremy Hylton <jeremy@alum.mit.edu>
date	Fri, 28 Jun 2002 23:38:14 +0000
parents	a5eeb288e020
children	1a9f47885260

rev	line source
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1 \chapter{Initialization, Finalization, and Threads
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	2 \label{initialization}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	3
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	4 \begin{cfuncdesc}{void}{Py_Initialize}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	5 Initialize the Python interpreter. In an application embedding
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	6 Python, this should be called before using any other Python/C API
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	7 functions; with the exception of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	8 \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()},
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	9 \cfunction{PyEval_InitThreads()}\ttindex{PyEval_InitThreads()},
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	10 \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()},
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	11 and \cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	12 This initializes the table of loaded modules (\code{sys.modules}),
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	13 and\withsubitem{(in module sys)}{\ttindex{modules}\ttindex{path}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	14 creates the fundamental modules
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	15 \module{__builtin__}\refbimodindex{__builtin__},
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	16 \module{__main__}\refbimodindex{__main__} and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	17 \module{sys}\refbimodindex{sys}. It also initializes the module
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	18 search\indexiii{module}{search}{path} path (\code{sys.path}).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	19 It does not set \code{sys.argv}; use
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	20 \cfunction{PySys_SetArgv()}\ttindex{PySys_SetArgv()} for that. This
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	21 is a no-op when called for a second time (without calling
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	22 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} first). There is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	23 no return value; it is a fatal error if the initialization fails.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	24 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	25
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	26 \begin{cfuncdesc}{int}{Py_IsInitialized}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	27 Return true (nonzero) when the Python interpreter has been
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	28 initialized, false (zero) if not. After \cfunction{Py_Finalize()}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	29 is called, this returns false until \cfunction{Py_Initialize()} is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	30 called again.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	31 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	32
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	33 \begin{cfuncdesc}{void}{Py_Finalize}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	34 Undo all initializations made by \cfunction{Py_Initialize()} and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	35 subsequent use of Python/C API functions, and destroy all
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	36 sub-interpreters (see \cfunction{Py_NewInterpreter()} below) that
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	37 were created and not yet destroyed since the last call to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	38 \cfunction{Py_Initialize()}. Ideally, this frees all memory
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	39 allocated by the Python interpreter. This is a no-op when called
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	40 for a second time (without calling \cfunction{Py_Initialize()} again
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	41 first). There is no return value; errors during finalization are
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	42 ignored.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	43
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	44 This function is provided for a number of reasons. An embedding
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	45 application might want to restart Python without having to restart
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	46 the application itself. An application that has loaded the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	47 interpreter from a dynamically loadable library (or DLL) might want
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	48 to free all memory allocated by Python before unloading the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	49 DLL. During a hunt for memory leaks in an application a developer
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	50 might want to free all memory allocated by Python before exiting
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	51 from the application.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	52
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	53 \strong{Bugs and caveats:} The destruction of modules and objects in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	54 modules is done in random order; this may cause destructors
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	55 (\method{__del__()} methods) to fail when they depend on other
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	56 objects (even functions) or modules. Dynamically loaded extension
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	57 modules loaded by Python are not unloaded. Small amounts of memory
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	58 allocated by the Python interpreter may not be freed (if you find a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	59 leak, please report it). Memory tied up in circular references
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	60 between objects is not freed. Some memory allocated by extension
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	61 modules may not be freed. Some extension may not work properly if
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	62 their initialization routine is called more than once; this can
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	63 happen if an applcation calls \cfunction{Py_Initialize()} and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	64 \cfunction{Py_Finalize()} more than once.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	65 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	66
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	67 \begin{cfuncdesc}{PyThreadState*}{Py_NewInterpreter}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	68 Create a new sub-interpreter. This is an (almost) totally separate
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	69 environment for the execution of Python code. In particular, the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	70 new interpreter has separate, independent versions of all imported
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	71 modules, including the fundamental modules
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	72 \module{__builtin__}\refbimodindex{__builtin__},
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	73 \module{__main__}\refbimodindex{__main__} and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	74 \module{sys}\refbimodindex{sys}. The table of loaded modules
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	75 (\code{sys.modules}) and the module search path (\code{sys.path})
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	76 are also separate. The new environment has no \code{sys.argv}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	77 variable. It has new standard I/O stream file objects
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	78 \code{sys.stdin}, \code{sys.stdout} and \code{sys.stderr} (however
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	79 these refer to the same underlying \ctype{FILE} structures in the C
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	80 library).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	81 \withsubitem{(in module sys)}{
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	82 \ttindex{stdout}\ttindex{stderr}\ttindex{stdin}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	83
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	84 The return value points to the first thread state created in the new
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	85 sub-interpreter. This thread state is made the current thread
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	86 state. Note that no actual thread is created; see the discussion of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	87 thread states below. If creation of the new interpreter is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	88 unsuccessful, \NULL{} is returned; no exception is set since the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	89 exception state is stored in the current thread state and there may
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	90 not be a current thread state. (Like all other Python/C API
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	91 functions, the global interpreter lock must be held before calling
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	92 this function and is still held when it returns; however, unlike
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	93 most other Python/C API functions, there needn't be a current thread
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	94 state on entry.)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	95
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	96 Extension modules are shared between (sub-)interpreters as follows:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	97 the first time a particular extension is imported, it is initialized
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	98 normally, and a (shallow) copy of its module's dictionary is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	99 squirreled away. When the same extension is imported by another
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	100 (sub-)interpreter, a new module is initialized and filled with the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	101 contents of this copy; the extension's \code{init} function is not
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	102 called. Note that this is different from what happens when an
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	103 extension is imported after the interpreter has been completely
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	104 re-initialized by calling
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	105 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	106 \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}; in that case,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	107 the extension's \code{init\var{module}} function \emph{is} called
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	108 again.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	109
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	110 \strong{Bugs and caveats:} Because sub-interpreters (and the main
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	111 interpreter) are part of the same process, the insulation between
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	112 them isn't perfect --- for example, using low-level file operations
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	113 like \withsubitem{(in module os)}{\ttindex{close()}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	114 \function{os.close()} they can (accidentally or maliciously) affect
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	115 each other's open files. Because of the way extensions are shared
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	116 between (sub-)interpreters, some extensions may not work properly;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	117 this is especially likely when the extension makes use of (static)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	118 global variables, or when the extension manipulates its module's
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	119 dictionary after its initialization. It is possible to insert
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	120 objects created in one sub-interpreter into a namespace of another
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	121 sub-interpreter; this should be done with great care to avoid
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	122 sharing user-defined functions, methods, instances or classes
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	123 between sub-interpreters, since import operations executed by such
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	124 objects may affect the wrong (sub-)interpreter's dictionary of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	125 loaded modules. (XXX This is a hard-to-fix bug that will be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	126 addressed in a future release.)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	127 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	128
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	129 \begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	130 Destroy the (sub-)interpreter represented by the given thread state.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	131 The given thread state must be the current thread state. See the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	132 discussion of thread states below. When the call returns, the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	133 current thread state is \NULL. All thread states associated with
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	134 this interpreted are destroyed. (The global interpreter lock must
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	135 be held before calling this function and is still held when it
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	136 returns.) \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} will
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	137 destroy all sub-interpreters that haven't been explicitly destroyed
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	138 at that point.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	139 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	140
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	141 \begin{cfuncdesc}{void}{Py_SetProgramName}{char *name}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	142 This function should be called before
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	143 \cfunction{Py_Initialize()}\ttindex{Py_Initialize()} is called
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	144 for the first time, if it is called at all. It tells the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	145 interpreter the value of the \code{argv[0]} argument to the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	146 \cfunction{main()}\ttindex{main()} function of the program. This is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	147 used by \cfunction{Py_GetPath()}\ttindex{Py_GetPath()} and some
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	148 other functions below to find the Python run-time libraries relative
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	149 to the interpreter executable. The default value is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	150 \code{'python'}. The argument should point to a zero-terminated
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	151 character string in static storage whose contents will not change
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	152 for the duration of the program's execution. No code in the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	153 interpreter will change the contents of this storage.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	154 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	155
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	156 \begin{cfuncdesc}{char*}{Py_GetProgramName}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	157 Return the program name set with
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	158 \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()}, or the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	159 default. The returned string points into static storage; the caller
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	160 should not modify its value.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	161 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	162
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	163 \begin{cfuncdesc}{char*}{Py_GetPrefix}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	164 Return the \emph{prefix} for installed platform-independent files.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	165 This is derived through a number of complicated rules from the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	166 program name set with \cfunction{Py_SetProgramName()} and some
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	167 environment variables; for example, if the program name is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	168 \code{'/usr/local/bin/python'}, the prefix is \code{'/usr/local'}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	169 The returned string points into static storage; the caller should
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	170 not modify its value. This corresponds to the \makevar{prefix}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	171 variable in the top-level \file{Makefile} and the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	172 \longprogramopt{prefix} argument to the \program{configure} script
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	173 at build time. The value is available to Python code as
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	174 \code{sys.prefix}. It is only useful on \UNIX. See also the next
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	175 function.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	176 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	177
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	178 \begin{cfuncdesc}{char*}{Py_GetExecPrefix}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	179 Return the \emph{exec-prefix} for installed
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	180 platform-\emph{de}pendent files. This is derived through a number
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	181 of complicated rules from the program name set with
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	182 \cfunction{Py_SetProgramName()} and some environment variables; for
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	183 example, if the program name is \code{'/usr/local/bin/python'}, the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	184 exec-prefix is \code{'/usr/local'}. The returned string points into
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	185 static storage; the caller should not modify its value. This
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	186 corresponds to the \makevar{exec_prefix} variable in the top-level
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	187 \file{Makefile} and the \longprogramopt{exec-prefix} argument to the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	188 \program{configure} script at build time. The value is available
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	189 to Python code as \code{sys.exec_prefix}. It is only useful on
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	190 \UNIX.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	191
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	192 Background: The exec-prefix differs from the prefix when platform
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	193 dependent files (such as executables and shared libraries) are
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	194 installed in a different directory tree. In a typical installation,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	195 platform dependent files may be installed in the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	196 \file{/usr/local/plat} subtree while platform independent may be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	197 installed in \file{/usr/local}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	198
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	199 Generally speaking, a platform is a combination of hardware and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	200 software families, e.g. Sparc machines running the Solaris 2.x
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	201 operating system are considered the same platform, but Intel
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	202 machines running Solaris 2.x are another platform, and Intel
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	203 machines running Linux are yet another platform. Different major
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	204 revisions of the same operating system generally also form different
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	205 platforms. Non-\UNIX{} operating systems are a different story; the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	206 installation strategies on those systems are so different that the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	207 prefix and exec-prefix are meaningless, and set to the empty string.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	208 Note that compiled Python bytecode files are platform independent
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	209 (but not independent from the Python version by which they were
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	210 compiled!).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	211
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	212 System administrators will know how to configure the \program{mount}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	213 or \program{automount} programs to share \file{/usr/local} between
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	214 platforms while having \file{/usr/local/plat} be a different
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	215 filesystem for each platform.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	216 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	217
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	218 \begin{cfuncdesc}{char*}{Py_GetProgramFullPath}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	219 Return the full program name of the Python executable; this is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	220 computed as a side-effect of deriving the default module search path
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	221 from the program name (set by
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	222 \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()} above).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	223 The returned string points into static storage; the caller should
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	224 not modify its value. The value is available to Python code as
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	225 \code{sys.executable}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	226 \withsubitem{(in module sys)}{\ttindex{executable}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	227 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	228
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	229 \begin{cfuncdesc}{char*}{Py_GetPath}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	230 \indexiii{module}{search}{path}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	231 Return the default module search path; this is computed from the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	232 program name (set by \cfunction{Py_SetProgramName()} above) and some
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	233 environment variables. The returned string consists of a series of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	234 directory names separated by a platform dependent delimiter
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	235 character. The delimiter character is \character{:} on \UNIX,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	236 \character{;} on DOS/Windows, and \character{\e n} (the \ASCII{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	237 newline character) on Macintosh. The returned string points into
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	238 static storage; the caller should not modify its value. The value
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	239 is available to Python code as the list
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	240 \code{sys.path}\withsubitem{(in module sys)}{\ttindex{path}}, which
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	241 may be modified to change the future search path for loaded
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	242 modules.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	243
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	244 % XXX should give the exact rules
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	245 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	246
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	247 \begin{cfuncdesc}{const char*}{Py_GetVersion}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	248 Return the version of this Python interpreter. This is a string
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	249 that looks something like
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	250
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	251 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	252 "1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]"
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	253 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	254
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	255 The first word (up to the first space character) is the current
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	256 Python version; the first three characters are the major and minor
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	257 version separated by a period. The returned string points into
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	258 static storage; the caller should not modify its value. The value
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	259 is available to Python code as the list \code{sys.version}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	260 \withsubitem{(in module sys)}{\ttindex{version}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	261 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	262
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	263 \begin{cfuncdesc}{const char*}{Py_GetPlatform}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	264 Return the platform identifier for the current platform. On \UNIX,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	265 this is formed from the ``official'' name of the operating system,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	266 converted to lower case, followed by the major revision number;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	267 e.g., for Solaris 2.x, which is also known as SunOS 5.x, the value
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	268 is \code{'sunos5'}. On Macintosh, it is \code{'mac'}. On Windows,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	269 it is \code{'win'}. The returned string points into static storage;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	270 the caller should not modify its value. The value is available to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	271 Python code as \code{sys.platform}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	272 \withsubitem{(in module sys)}{\ttindex{platform}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	273 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	274
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	275 \begin{cfuncdesc}{const char*}{Py_GetCopyright}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	276 Return the official copyright string for the current Python version,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	277 for example
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	278
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	279 \code{'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	280
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	281 The returned string points into static storage; the caller should
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	282 not modify its value. The value is available to Python code as the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	283 list \code{sys.copyright}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	284 \withsubitem{(in module sys)}{\ttindex{copyright}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	285 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	286
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	287 \begin{cfuncdesc}{const char*}{Py_GetCompiler}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	288 Return an indication of the compiler used to build the current
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	289 Python version, in square brackets, for example:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	290
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	291 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	292 "[GCC 2.7.2.2]"
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	293 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	294
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	295 The returned string points into static storage; the caller should
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	296 not modify its value. The value is available to Python code as part
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	297 of the variable \code{sys.version}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	298 \withsubitem{(in module sys)}{\ttindex{version}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	299 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	300
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	301 \begin{cfuncdesc}{const char*}{Py_GetBuildInfo}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	302 Return information about the sequence number and build date and time
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	303 of the current Python interpreter instance, for example
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	304
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	305 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	306 "#67, Aug 1 1997, 22:34:28"
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	307 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	308
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	309 The returned string points into static storage; the caller should
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	310 not modify its value. The value is available to Python code as part
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	311 of the variable \code{sys.version}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	312 \withsubitem{(in module sys)}{\ttindex{version}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	313 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	314
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	315 \begin{cfuncdesc}{int}{PySys_SetArgv}{int argc, char **argv}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	316 Set \code{sys.argv} based on \var{argc} and \var{argv}. These
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	317 parameters are similar to those passed to the program's
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	318 \cfunction{main()}\ttindex{main()} function with the difference that
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	319 the first entry should refer to the script file to be executed
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	320 rather than the executable hosting the Python interpreter. If there
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	321 isn't a script that will be run, the first entry in \var{argv} can
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	322 be an empty string. If this function fails to initialize
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	323 \code{sys.argv}, a fatal condition is signalled using
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	324 \cfunction{Py_FatalError()}\ttindex{Py_FatalError()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	325 \withsubitem{(in module sys)}{\ttindex{argv}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	326 % XXX impl. doesn't seem consistent in allowing 0/NULL for the params;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	327 % check w/ Guido.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	328 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	329
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	330 % XXX Other PySys thingies (doesn't really belong in this chapter)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	331
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	332 \section{Thread State and the Global Interpreter Lock
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	333 \label{threads}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	334
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	335 \index{global interpreter lock}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	336 \index{interpreter lock}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	337 \index{lock, interpreter}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	338
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	339 The Python interpreter is not fully thread safe. In order to support
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	340 multi-threaded Python programs, there's a global lock that must be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	341 held by the current thread before it can safely access Python objects.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	342 Without the lock, even the simplest operations could cause problems in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	343 a multi-threaded program: for example, when two threads simultaneously
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	344 increment the reference count of the same object, the reference count
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	345 could end up being incremented only once instead of twice.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	346
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	347 Therefore, the rule exists that only the thread that has acquired the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	348 global interpreter lock may operate on Python objects or call Python/C
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	349 API functions. In order to support multi-threaded Python programs,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	350 the interpreter regularly releases and reacquires the lock --- by
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	351 default, every ten bytecode instructions (this can be changed with
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	352 \withsubitem{(in module sys)}{\ttindex{setcheckinterval()}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	353 \function{sys.setcheckinterval()}). The lock is also released and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	354 reacquired around potentially blocking I/O operations like reading or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	355 writing a file, so that other threads can run while the thread that
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	356 requests the I/O is waiting for the I/O operation to complete.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	357
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	358 The Python interpreter needs to keep some bookkeeping information
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	359 separate per thread --- for this it uses a data structure called
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	360 \ctype{PyThreadState}\ttindex{PyThreadState}. This is new in Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	361 1.5; in earlier versions, such state was stored in global variables,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	362 and switching threads could cause problems. In particular, exception
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	363 handling is now thread safe, when the application uses
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	364 \withsubitem{(in module sys)}{\ttindex{exc_info()}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	365 \function{sys.exc_info()} to access the exception last raised in the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	366 current thread.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	367
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	368 There's one global variable left, however: the pointer to the current
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	369 \ctype{PyThreadState}\ttindex{PyThreadState} structure. While most
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	370 thread packages have a way to store ``per-thread global data,''
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	371 Python's internal platform independent thread abstraction doesn't
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	372 support this yet. Therefore, the current thread state must be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	373 manipulated explicitly.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	374
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	375 This is easy enough in most cases. Most code manipulating the global
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	376 interpreter lock has the following simple structure:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	377
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	378 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	379 Save the thread state in a local variable.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	380 Release the interpreter lock.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	381 ...Do some blocking I/O operation...
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	382 Reacquire the interpreter lock.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	383 Restore the thread state from the local variable.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	384 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	385
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	386 This is so common that a pair of macros exists to simplify it:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	387
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	388 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	389 Py_BEGIN_ALLOW_THREADS
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	390 ...Do some blocking I/O operation...
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	391 Py_END_ALLOW_THREADS
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	392 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	393
22923 a5eeb288e020 Update to use the new \csimplemacro macro Fred Drake <fdrake@acm.org> parents: 20460 diff changeset	394 The
a5eeb288e020 Update to use the new \csimplemacro macro Fred Drake <fdrake@acm.org> parents: 20460 diff changeset	395 \csimplemacro{Py_BEGIN_ALLOW_THREADS}\ttindex{Py_BEGIN_ALLOW_THREADS}
a5eeb288e020 Update to use the new \csimplemacro macro Fred Drake <fdrake@acm.org> parents: 20460 diff changeset	396 macro opens a new block and declares a hidden local variable; the
a5eeb288e020 Update to use the new \csimplemacro macro Fred Drake <fdrake@acm.org> parents: 20460 diff changeset	397 \csimplemacro{Py_END_ALLOW_THREADS}\ttindex{Py_END_ALLOW_THREADS}
a5eeb288e020 Update to use the new \csimplemacro macro Fred Drake <fdrake@acm.org> parents: 20460 diff changeset	398 macro closes the block. Another advantage of using these two macros
a5eeb288e020 Update to use the new \csimplemacro macro Fred Drake <fdrake@acm.org> parents: 20460 diff changeset	399 is that when Python is compiled without thread support, they are
a5eeb288e020 Update to use the new \csimplemacro macro Fred Drake <fdrake@acm.org> parents: 20460 diff changeset	400 defined empty, thus saving the thread state and lock manipulations.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	401
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	402 When thread support is enabled, the block above expands to the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	403 following code:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	404
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	405 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	406 PyThreadState *_save;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	407
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	408 _save = PyEval_SaveThread();
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	409 ...Do some blocking I/O operation...
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	410 PyEval_RestoreThread(_save);
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	411 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	412
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	413 Using even lower level primitives, we can get roughly the same effect
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	414 as follows:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	415
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	416 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	417 PyThreadState *_save;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	418
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	419 _save = PyThreadState_Swap(NULL);
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	420 PyEval_ReleaseLock();
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	421 ...Do some blocking I/O operation...
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	422 PyEval_AcquireLock();
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	423 PyThreadState_Swap(_save);
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	424 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	425
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	426 There are some subtle differences; in particular,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	427 \cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()} saves
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	428 and restores the value of the global variable
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	429 \cdata{errno}\ttindex{errno}, since the lock manipulation does not
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	430 guarantee that \cdata{errno} is left alone. Also, when thread support
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	431 is disabled,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	432 \cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	433 \cfunction{PyEval_RestoreThread()} don't manipulate the lock; in this
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	434 case, \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	435 \cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()} are not
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	436 available. This is done so that dynamically loaded extensions
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	437 compiled with thread support enabled can be loaded by an interpreter
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	438 that was compiled with disabled thread support.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	439
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	440 The global interpreter lock is used to protect the pointer to the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	441 current thread state. When releasing the lock and saving the thread
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	442 state, the current thread state pointer must be retrieved before the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	443 lock is released (since another thread could immediately acquire the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	444 lock and store its own thread state in the global variable).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	445 Conversely, when acquiring the lock and restoring the thread state,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	446 the lock must be acquired before storing the thread state pointer.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	447
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	448 Why am I going on with so much detail about this? Because when
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	449 threads are created from C, they don't have the global interpreter
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	450 lock, nor is there a thread state data structure for them. Such
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	451 threads must bootstrap themselves into existence, by first creating a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	452 thread state data structure, then acquiring the lock, and finally
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	453 storing their thread state pointer, before they can start using the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	454 Python/C API. When they are done, they should reset the thread state
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	455 pointer, release the lock, and finally free their thread state data
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	456 structure.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	457
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	458 When creating a thread data structure, you need to provide an
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	459 interpreter state data structure. The interpreter state data
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	460 structure hold global data that is shared by all threads in an
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	461 interpreter, for example the module administration
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	462 (\code{sys.modules}). Depending on your needs, you can either create
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	463 a new interpreter state data structure, or share the interpreter state
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	464 data structure used by the Python main thread (to access the latter,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	465 you must obtain the thread state and access its \member{interp} member;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	466 this must be done by a thread that is created by Python or by the main
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	467 thread after Python is initialized).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	468
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	469
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	470 \begin{ctypedesc}{PyInterpreterState}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	471 This data structure represents the state shared by a number of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	472 cooperating threads. Threads belonging to the same interpreter
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	473 share their module administration and a few other internal items.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	474 There are no public members in this structure.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	475
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	476 Threads belonging to different interpreters initially share nothing,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	477 except process state like available memory, open file descriptors
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	478 and such. The global interpreter lock is also shared by all
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	479 threads, regardless of to which interpreter they belong.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	480 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	481
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	482 \begin{ctypedesc}{PyThreadState}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	483 This data structure represents the state of a single thread. The
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	484 only public data member is \ctype{PyInterpreterState
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	485 *}\member{interp}, which points to this thread's interpreter state.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	486 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	487
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	488 \begin{cfuncdesc}{void}{PyEval_InitThreads}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	489 Initialize and acquire the global interpreter lock. It should be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	490 called in the main thread before creating a second thread or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	491 engaging in any other thread operations such as
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	492 \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	493 \code{PyEval_ReleaseThread(\var{tstate})}\ttindex{PyEval_ReleaseThread()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	494 It is not needed before calling
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	495 \cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	496 \cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	497
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	498 This is a no-op when called for a second time. It is safe to call
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	499 this function before calling
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	500 \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	501
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	502 When only the main thread exists, no lock operations are needed.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	503 This is a common situation (most Python programs do not use
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	504 threads), and the lock operations slow the interpreter down a bit.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	505 Therefore, the lock is not created initially. This situation is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	506 equivalent to having acquired the lock: when there is only a single
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	507 thread, all object accesses are safe. Therefore, when this function
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	508 initializes the lock, it also acquires it. Before the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	509 \module{thread}\refbimodindex{thread} module creates a new thread,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	510 knowing that either it has the lock or the lock hasn't been created
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	511 yet, it calls \cfunction{PyEval_InitThreads()}. When this call
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	512 returns, it is guaranteed that the lock has been created and that it
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	513 has acquired it.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	514
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	515 It is \strong{not} safe to call this function when it is unknown
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	516 which thread (if any) currently has the global interpreter lock.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	517
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	518 This function is not available when thread support is disabled at
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	519 compile time.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	520 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	521
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	522 \begin{cfuncdesc}{void}{PyEval_AcquireLock}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	523 Acquire the global interpreter lock. The lock must have been
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	524 created earlier. If this thread already has the lock, a deadlock
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	525 ensues. This function is not available when thread support is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	526 disabled at compile time.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	527 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	528
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	529 \begin{cfuncdesc}{void}{PyEval_ReleaseLock}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	530 Release the global interpreter lock. The lock must have been
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	531 created earlier. This function is not available when thread support
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	532 is disabled at compile time.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	533 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	534
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	535 \begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	536 Acquire the global interpreter lock and then set the current thread
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	537 state to \var{tstate}, which should not be \NULL. The lock must
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	538 have been created earlier. If this thread already has the lock,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	539 deadlock ensues. This function is not available when thread support
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	540 is disabled at compile time.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	541 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	542
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	543 \begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	544 Reset the current thread state to \NULL{} and release the global
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	545 interpreter lock. The lock must have been created earlier and must
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	546 be held by the current thread. The \var{tstate} argument, which
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	547 must not be \NULL, is only used to check that it represents the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	548 current thread state --- if it isn't, a fatal error is reported.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	549 This function is not available when thread support is disabled at
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	550 compile time.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	551 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	552
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	553 \begin{cfuncdesc}{PyThreadState*}{PyEval_SaveThread}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	554 Release the interpreter lock (if it has been created and thread
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	555 support is enabled) and reset the thread state to \NULL, returning
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	556 the previous thread state (which is not \NULL). If the lock has
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	557 been created, the current thread must have acquired it. (This
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	558 function is available even when thread support is disabled at
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	559 compile time.)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	560 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	561
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	562 \begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	563 Acquire the interpreter lock (if it has been created and thread
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	564 support is enabled) and set the thread state to \var{tstate}, which
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	565 must not be \NULL. If the lock has been created, the current thread
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	566 must not have acquired it, otherwise deadlock ensues. (This
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	567 function is available even when thread support is disabled at
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	568 compile time.)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	569 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	570
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	571 The following macros are normally used without a trailing semicolon;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	572 look for example usage in the Python source distribution.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	573
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	574 \begin{csimplemacrodesc}{Py_BEGIN_ALLOW_THREADS}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	575 This macro expands to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	576 \samp{\{ PyThreadState *_save; _save = PyEval_SaveThread();}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	577 Note that it contains an opening brace; it must be matched with a
22923 a5eeb288e020 Update to use the new \csimplemacro macro Fred Drake <fdrake@acm.org> parents: 20460 diff changeset	578 following \csimplemacro{Py_END_ALLOW_THREADS} macro. See above for
a5eeb288e020 Update to use the new \csimplemacro macro Fred Drake <fdrake@acm.org> parents: 20460 diff changeset	579 further discussion of this macro. It is a no-op when thread support
a5eeb288e020 Update to use the new \csimplemacro macro Fred Drake <fdrake@acm.org> parents: 20460 diff changeset	580 is disabled at compile time.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	581 \end{csimplemacrodesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	582
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	583 \begin{csimplemacrodesc}{Py_END_ALLOW_THREADS}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	584 This macro expands to \samp{PyEval_RestoreThread(_save); \}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	585 Note that it contains a closing brace; it must be matched with an
22923 a5eeb288e020 Update to use the new \csimplemacro macro Fred Drake <fdrake@acm.org> parents: 20460 diff changeset	586 earlier \csimplemacro{Py_BEGIN_ALLOW_THREADS} macro. See above for
a5eeb288e020 Update to use the new \csimplemacro macro Fred Drake <fdrake@acm.org> parents: 20460 diff changeset	587 further discussion of this macro. It is a no-op when thread support
a5eeb288e020 Update to use the new \csimplemacro macro Fred Drake <fdrake@acm.org> parents: 20460 diff changeset	588 is disabled at compile time.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	589 \end{csimplemacrodesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	590
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	591 \begin{csimplemacrodesc}{Py_BLOCK_THREADS}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	592 This macro expands to \samp{PyEval_RestoreThread(_save);}: it is
22923 a5eeb288e020 Update to use the new \csimplemacro macro Fred Drake <fdrake@acm.org> parents: 20460 diff changeset	593 equivalent to \csimplemacro{Py_END_ALLOW_THREADS} without the
a5eeb288e020 Update to use the new \csimplemacro macro Fred Drake <fdrake@acm.org> parents: 20460 diff changeset	594 closing brace. It is a no-op when thread support is disabled at
a5eeb288e020 Update to use the new \csimplemacro macro Fred Drake <fdrake@acm.org> parents: 20460 diff changeset	595 compile time.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	596 \end{csimplemacrodesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	597
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	598 \begin{csimplemacrodesc}{Py_UNBLOCK_THREADS}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	599 This macro expands to \samp{_save = PyEval_SaveThread();}: it is
22923 a5eeb288e020 Update to use the new \csimplemacro macro Fred Drake <fdrake@acm.org> parents: 20460 diff changeset	600 equivalent to \csimplemacro{Py_BEGIN_ALLOW_THREADS} without the
a5eeb288e020 Update to use the new \csimplemacro macro Fred Drake <fdrake@acm.org> parents: 20460 diff changeset	601 opening brace and variable declaration. It is a no-op when thread
a5eeb288e020 Update to use the new \csimplemacro macro Fred Drake <fdrake@acm.org> parents: 20460 diff changeset	602 support is disabled at compile time.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	603 \end{csimplemacrodesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	604
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	605 All of the following functions are only available when thread support
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	606 is enabled at compile time, and must be called only when the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	607 interpreter lock has been created.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	608
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	609 \begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_New}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	610 Create a new interpreter state object. The interpreter lock need
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	611 not be held, but may be held if it is necessary to serialize calls
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	612 to this function.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	613 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	614
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	615 \begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	616 Reset all information in an interpreter state object. The
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	617 interpreter lock must be held.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	618 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	619
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	620 \begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	621 Destroy an interpreter state object. The interpreter lock need not
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	622 be held. The interpreter state must have been reset with a previous
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	623 call to \cfunction{PyInterpreterState_Clear()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	624 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	625
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	626 \begin{cfuncdesc}{PyThreadState}{PyThreadState_New}{PyInterpreterState interp}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	627 Create a new thread state object belonging to the given interpreter
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	628 object. The interpreter lock need not be held, but may be held if
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	629 it is necessary to serialize calls to this function.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	630 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	631
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	632 \begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	633 Reset all information in a thread state object. The interpreter lock
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	634 must be held.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	635 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	636
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	637 \begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	638 Destroy a thread state object. The interpreter lock need not be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	639 held. The thread state must have been reset with a previous call to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	640 \cfunction{PyThreadState_Clear()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	641 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	642
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	643 \begin{cfuncdesc}{PyThreadState*}{PyThreadState_Get}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	644 Return the current thread state. The interpreter lock must be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	645 held. When the current thread state is \NULL, this issues a fatal
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	646 error (so that the caller needn't check for \NULL).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	647 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	648
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	649 \begin{cfuncdesc}{PyThreadState}{PyThreadState_Swap}{PyThreadState tstate}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	650 Swap the current thread state with the thread state given by the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	651 argument \var{tstate}, which may be \NULL. The interpreter lock
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	652 must be held.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	653 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	654
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	655 \begin{cfuncdesc}{PyObject*}{PyThreadState_GetDict}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	656 Return a dictionary in which extensions can store thread-specific
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	657 state information. Each extension should use a unique key to use to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	658 store state in the dictionary. If this function returns \NULL, an
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	659 exception has been raised and the caller should allow it to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	660 propogate.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	661 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	662
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	663
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	664 \section{Profiling and Tracing \label{profiling}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	665
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	666 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	667
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	668 The Python interpreter provides some low-level support for attaching
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	669 profiling and execution tracing facilities. These are used for
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	670 profiling, debugging, and coverage analysis tools.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	671
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	672 Starting with Python 2.2, the implementation of this facility was
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	673 substantially revised, and an interface from C was added. This C
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	674 interface allows the profiling or tracing code to avoid the overhead
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	675 of calling through Python-level callable objects, making a direct C
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	676 function call instead. The essential attributes of the facility have
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	677 not changed; the interface allows trace functions to be installed
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	678 per-thread, and the basic events reported to the trace function are
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	679 the same as had been reported to the Python-level trace functions in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	680 previous versions.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	681
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	682 \begin{ctypedesc}[Py_tracefunc]{int (Py_tracefunc)(PyObject obj,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	683 PyFrameObject *frame, int what,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	684 PyObject *arg)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	685 The type of the trace function registered using
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	686 \cfunction{PyEval_SetProfile()} and \cfunction{PyEval_SetTrace()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	687 The first parameter is the object passed to the registration
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	688 function as \var{obj}, \var{frame} is the frame object to which the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	689 event pertains, \var{what} is one of the constants
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	690 \constant{PyTrace_CALL}, \constant{PyTrace_EXCEPT},
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	691 \constant{PyTrace_LINE} or \constant{PyTrace_RETURN}, and \var{arg}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	692 depends on the value of \var{what}:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	693
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	694 \begin{tableii}{l\|l}{constant}{Value of \var{what}}{Meaning of \var{arg}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	695 \lineii{PyTrace_CALL}{Always \NULL.}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	696 \lineii{PyTrace_EXCEPT}{Exception information as returned by
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	697 \function{sys.exc_info()}.}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	698 \lineii{PyTrace_LINE}{Always \NULL.}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	699 \lineii{PyTrace_RETURN}{Value being returned to the caller.}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	700 \end{tableii}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	701 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	702
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	703 \begin{cvardesc}{int}{PyTrace_CALL}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	704 The value of the \var{what} parameter to a \ctype{Py_tracefunc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	705 function when a new call to a function or method is being reported,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	706 or a new entry into a generator. Note that the creation of the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	707 iterator for a generator function is not reported as there is no
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	708 control transfer to the Python bytecode in the corresponding frame.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	709 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	710
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	711 \begin{cvardesc}{int}{PyTrace_EXCEPT}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	712 The value of the \var{what} parameter to a \ctype{Py_tracefunc}
20460 ffbf94fd9cef Update the description of PyTrace_EXCEPT. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	713 function when an exception has been raised. The callback function
ffbf94fd9cef Update the description of PyTrace_EXCEPT. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	714 is called with this value for \var{what} when after any bytecode is
ffbf94fd9cef Update the description of PyTrace_EXCEPT. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	715 processed after which the exception becomes set within the frame
ffbf94fd9cef Update the description of PyTrace_EXCEPT. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	716 being executed. The effect of this is that as exception propogation
ffbf94fd9cef Update the description of PyTrace_EXCEPT. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	717 causes the Python stack to unwind, the callback is called upon
ffbf94fd9cef Update the description of PyTrace_EXCEPT. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	718 return to each frame as the exception propogates. Only trace
ffbf94fd9cef Update the description of PyTrace_EXCEPT. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	719 functions receives these events; they are not needed by the
ffbf94fd9cef Update the description of PyTrace_EXCEPT. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	720 profiler.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	721 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	722
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	723 \begin{cvardesc}{int}{PyTrace_LINE}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	724 The value passed as the \var{what} parameter to a trace function
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	725 (but not a profiling function) when a line-number event is being
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	726 reported.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	727 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	728
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	729 \begin{cvardesc}{int}{PyTrace_RETURN}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	730 The value for the \var{what} parameter to \ctype{Py_tracefunc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	731 functions when a call is returning without propogating an exception.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	732 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	733
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	734 \begin{cfuncdesc}{void}{PyEval_SetProfile}{Py_tracefunc func, PyObject *obj}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	735 Set the profiler function to \var{func}. The \var{obj} parameter is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	736 passed to the function as its first parameter, and may be any Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	737 object, or \NULL. If the profile function needs to maintain state,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	738 using a different value for \var{obj} for each thread provides a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	739 convenient and thread-safe place to store it. The profile function
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	740 is called for all monitored events except the line-number events.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	741 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	742
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	743 \begin{cfuncdesc}{void}{PyEval_SetTrace}{Py_tracefunc func, PyObject *obj}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	744 Set the the tracing function to \var{func}. This is similar to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	745 \cfunction{PyEval_SetProfile()}, except the tracing function does
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	746 receive line-number events.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	747 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	748
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	749
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	750 \section{Advanced Debugger Support \label{advanced-debugging}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	751 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	752
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	753 These functions are only intended to be used by advanced debugging
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	754 tools.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	755
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	756 \begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Head}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	757 Return the interpreter state object at the head of the list of all
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	758 such objects.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	759 \versionadded{2.2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	760 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	761
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	762 \begin{cfuncdesc}{PyInterpreterState}{PyInterpreterState_Next}{PyInterpreterState interp}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	763 Return the next interpreter state object after \var{interp} from the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	764 list of all such objects.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	765 \versionadded{2.2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	766 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	767
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	768 \begin{cfuncdesc}{PyThreadState }{PyInterpreterState_ThreadHead}{PyInterpreterState interp}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	769 Return the a pointer to the first \ctype{PyThreadState} object in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	770 the list of threads associated with the interpreter \var{interp}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	771 \versionadded{2.2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	772 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	773
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	774 \begin{cfuncdesc}{PyThreadState}{PyThreadState_Next}{PyThreadState tstate}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	775 Return the next thread state object after \var{tstate} from the list
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	776 of all such objects belonging to the same \ctype{PyInterpreterState}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	777 object.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	778 \versionadded{2.2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	779 \end{cfuncdesc}

Mercurial > cpython-lru_cache-weakref

annotate Doc/api/init.tex @ 24042:63fbbed10714 legacy-trunk