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

annotate Doc/api/init.tex @ 39940:dfd809dcf680 2.5

Bug #1446043: correctly raise a LookupError if an encoding name given to encodings.search_function() contains a dot. (backport from rev. 52075)

author	Georg Brandl <georg@python.org>
date	Sat, 30 Sep 2006 11:22:35 +0000
parents	de9e1a5dca93
children	06145fbc7ab9

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
33189 de804edf8bcd Patch #900727: Add Py_InitializeEx to allow embedding without signals. Martin v. Löwis <martin@v.loewis.de> parents: 32575 diff changeset	26 \begin{cfuncdesc}{void}{Py_InitializeEx}{int initsigs}
33715 a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick Tim Peters <tim.peters@gmail.com> parents: 33189 diff changeset	27 This function works like \cfunction{Py_Initialize()} if
33189 de804edf8bcd Patch #900727: Add Py_InitializeEx to allow embedding without signals. Martin v. Löwis <martin@v.loewis.de> parents: 32575 diff changeset	28 \var{initsigs} is 1. If \var{initsigs} is 0, it skips
de804edf8bcd Patch #900727: Add Py_InitializeEx to allow embedding without signals. Martin v. Löwis <martin@v.loewis.de> parents: 32575 diff changeset	29 initialization registration of signal handlers, which
de804edf8bcd Patch #900727: Add Py_InitializeEx to allow embedding without signals. Martin v. Löwis <martin@v.loewis.de> parents: 32575 diff changeset	30 might be useful when Python is embedded. \versionadded{2.4}
de804edf8bcd Patch #900727: Add Py_InitializeEx to allow embedding without signals. Martin v. Löwis <martin@v.loewis.de> parents: 32575 diff changeset	31 \end{cfuncdesc}
de804edf8bcd Patch #900727: Add Py_InitializeEx to allow embedding without signals. Martin v. Löwis <martin@v.loewis.de> parents: 32575 diff changeset	32
20390 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}{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	34 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	35 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	36 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	37 called again.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	38 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	39
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	40 \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	41 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	42 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	43 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	44 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	45 \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	46 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	47 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	48 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	49 ignored.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	50
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	51 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	52 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	53 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	54 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	55 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	56 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	57 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	58 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	59
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	60 \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	61 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	62 (\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	63 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	64 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	65 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	66 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	67 between objects is not freed. Some memory allocated by extension
27798 e62099c65a3c A typo, and desist from inaccurately describing some things as lists. Michael W. Hudson <mwh@python.net> parents: 26558 diff changeset	68 modules may not be freed. Some extensions may not work properly if
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	69 their initialization routine is called more than once; this can
27798 e62099c65a3c A typo, and desist from inaccurately describing some things as lists. Michael W. Hudson <mwh@python.net> parents: 26558 diff changeset	70 happen if an application calls \cfunction{Py_Initialize()} and
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	71 \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	72 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	73
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	74 \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	75 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	76 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	77 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	78 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	79 \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	80 \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	81 \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	82 (\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	83 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	84 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	85 \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	86 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	87 library).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	88 \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	89 \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	90
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	91 The return value points to the first thread state created in the new
31679 da78b96b6aab Minor grammatical fixes. Brett Cannon <bcannon@gmail.com> parents: 31678 diff changeset	92 sub-interpreter. This thread state is made in the current thread
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	93 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	94 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	95 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	96 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	97 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	98 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	99 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	100 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	101 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	102
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	103 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	104 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	105 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	106 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	107 (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	108 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	109 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	110 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	111 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	112 \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	113 \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	114 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	115 again.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	116
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	117 \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	118 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	119 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	120 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	121 \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	122 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	123 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	124 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	125 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	126 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	127 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	128 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	129 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	130 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	131 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	132 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	133 addressed in a future release.)
35116 2fb0c76d0251 Add a(nother) warning about mixing Py_NewInterpreter and the Michael W. Hudson <mwh@python.net> parents: 35114 diff changeset	134
2fb0c76d0251 Add a(nother) warning about mixing Py_NewInterpreter and the Michael W. Hudson <mwh@python.net> parents: 35114 diff changeset	135 Also note that the use of this functionality is incompatible with
2fb0c76d0251 Add a(nother) warning about mixing Py_NewInterpreter and the Michael W. Hudson <mwh@python.net> parents: 35114 diff changeset	136 extension modules such as PyObjC and ctypes that use the
2fb0c76d0251 Add a(nother) warning about mixing Py_NewInterpreter and the Michael W. Hudson <mwh@python.net> parents: 35114 diff changeset	137 \cfunction{PyGILState_*} APIs (and this is inherent in the way the
2fb0c76d0251 Add a(nother) warning about mixing Py_NewInterpreter and the Michael W. Hudson <mwh@python.net> parents: 35114 diff changeset	138 \cfunction{PyGILState_*} functions work). Simple things may work,
2fb0c76d0251 Add a(nother) warning about mixing Py_NewInterpreter and the Michael W. Hudson <mwh@python.net> parents: 35114 diff changeset	139 but confusing behavior will always be near.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	140 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	141
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	142 \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	143 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	144 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	145 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	146 current thread state is \NULL. All thread states associated with
31678 c0a542a1fc1c Extremely minor typo fixed. Brett Cannon <bcannon@gmail.com> parents: 30715 diff changeset	147 this interpreter are destroyed. (The global interpreter lock must
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	148 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	149 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	150 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	151 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	152 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	153
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	154 \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	155 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	156 \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	157 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	158 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	159 \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	160 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	161 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	162 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	163 \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	164 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	165 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	166 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	167 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	168
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	169 \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	170 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	171 \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	172 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	173 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	174 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	175
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	176 \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	177 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	178 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	179 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	180 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	181 \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	182 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	183 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	184 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	185 \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	186 at build time. The value is available to Python code as
36767 e364bc76bdc8 Fix warning that texcheck complained about. Martin v. Löwis <martin@v.loewis.de> parents: 36754 diff changeset	187 \code{sys.prefix}. It is only useful on \UNIX{}. See also the next
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	188 function.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	189 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	190
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	191 \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	192 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	193 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	194 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	195 \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	196 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	197 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	198 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	199 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	200 \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	201 \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	202 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	203 \UNIX.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	204
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	205 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	206 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	207 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	208 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	209 \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	210 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	211
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	212 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	213 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	214 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	215 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	216 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	217 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	218 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	219 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	220 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	221 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	222 (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	223 compiled!).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	224
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	225 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	226 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	227 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	228 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	229 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	230
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	231 \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	232 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	233 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	234 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	235 \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	236 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	237 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	238 \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	239 \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	240 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	241
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	242 \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	243 \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	244 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	245 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	246 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	247 directory names separated by a platform dependent delimiter
34586 7e7e86f45255 Update refences to "Macintosh" to reflect the state of affairs for OS X and not Brett Cannon <bcannon@gmail.com> parents: 34452 diff changeset	248 character. The delimiter character is \character{:} on \UNIX and Mac OS X,
7e7e86f45255 Update refences to "Macintosh" to reflect the state of affairs for OS X and not Brett Cannon <bcannon@gmail.com> parents: 34452 diff changeset	249 \character{;} on Windows. The returned string points into
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	250 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	251 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	252 \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	253 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	254 modules.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	255
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	256 % 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	257 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	258
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	259 \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	260 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	261 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	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{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	264 "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	265 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	266
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	267 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	268 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	269 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	270 static storage; the caller should not modify its value. The value
27798 e62099c65a3c A typo, and desist from inaccurately describing some things as lists. Michael W. Hudson <mwh@python.net> parents: 26558 diff changeset	271 is available to Python code as \code{sys.version}.
20390 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{version}}
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
36070 9697eeeaf246 Expose Subversion revision number (calculated via "svnversion .") to Python. Barry Warsaw <barry@python.org> parents: 35116 diff changeset	275 \begin{cfuncdesc}{const char*}{Py_GetBuildNumber}{}
9697eeeaf246 Expose Subversion revision number (calculated via "svnversion .") to Python. Barry Warsaw <barry@python.org> parents: 35116 diff changeset	276 Return a string representing the Subversion revision that this Python
9697eeeaf246 Expose Subversion revision number (calculated via "svnversion .") to Python. Barry Warsaw <barry@python.org> parents: 35116 diff changeset	277 executable was built from. This number is a string because it may contain a
9697eeeaf246 Expose Subversion revision number (calculated via "svnversion .") to Python. Barry Warsaw <barry@python.org> parents: 35116 diff changeset	278 trailing 'M' if Python was built from a mixed revision source tree.
36071 45f7b7383a4e Add versionadded info Neal Norwitz <nnorwitz@gmail.com> parents: 36070 diff changeset	279 \versionadded{2.5}
36070 9697eeeaf246 Expose Subversion revision number (calculated via "svnversion .") to Python. Barry Warsaw <barry@python.org> parents: 35116 diff changeset	280 \end{cfuncdesc}
9697eeeaf246 Expose Subversion revision number (calculated via "svnversion .") to Python. Barry Warsaw <barry@python.org> parents: 35116 diff changeset	281
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	282 \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	283 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	284 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	285 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	286 e.g., for Solaris 2.x, which is also known as SunOS 5.x, the value
34586 7e7e86f45255 Update refences to "Macintosh" to reflect the state of affairs for OS X and not Brett Cannon <bcannon@gmail.com> parents: 34452 diff changeset	287 is \code{'sunos5'}. On Mac OS X, it is \code{'darwin'}. On Windows,
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	288 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	289 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	290 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	291 \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	292 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	293
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	294 \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	295 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	296 for example
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	297
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	298 \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	299
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	300 The returned string points into static storage; the caller should
27798 e62099c65a3c A typo, and desist from inaccurately describing some things as lists. Michael W. Hudson <mwh@python.net> parents: 26558 diff changeset	301 not modify its value. The value is available to Python code as
e62099c65a3c A typo, and desist from inaccurately describing some things as lists. Michael W. Hudson <mwh@python.net> parents: 26558 diff changeset	302 \code{sys.copyright}.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	303 \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	304 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	305
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	306 \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	307 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	308 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	309
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	310 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	311 "[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	312 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	313
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	314 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	315 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	316 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	317 \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	318 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	319
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	320 \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	321 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	322 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	323
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	324 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	325 "#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	326 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	327
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	328 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	329 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	330 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	331 \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	332 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	333
36754 2f19b981ac24 Make documentation match the implementation. Martin v. Löwis <martin@v.loewis.de> parents: 36071 diff changeset	334 \begin{cfuncdesc}{void}{PySys_SetArgv}{int argc, char **argv}
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	335 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	336 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	337 \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	338 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	339 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	340 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	341 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	342 \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	343 \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	344 \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	345 % 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	346 % 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	347 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	348
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	349 % 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	350
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	351 \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	352 \label{threads}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	353
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	354 \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	355 \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	356 \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	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 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	359 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	360 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	361 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	362 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	363 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	364 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	365
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	366 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	367 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	368 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	369 the interpreter regularly releases and reacquires the lock --- by
29750 b86446f0350f Correct documentation of check interval - it's 100 by default, not 10 any Skip Montanaro <skip@pobox.com> parents: 29649 diff changeset	370 default, every 100 bytecode instructions (this can be changed with
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	371 \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	372 \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	373 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	374 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	375 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	376
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	377 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	378 separate per thread --- for this it uses a data structure called
32575 511ffc62b298 Remove a few elderly sentences Andrew M. Kuchling <amk@amk.ca> parents: 32574 diff changeset	379 \ctype{PyThreadState}\ttindex{PyThreadState}. There's one global
511ffc62b298 Remove a few elderly sentences Andrew M. Kuchling <amk@amk.ca> parents: 32574 diff changeset	380 variable, however: the pointer to the current
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	381 \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	382 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	383 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	384 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	385 manipulated explicitly.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	386
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	387 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	388 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	389
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	390 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	391 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	392 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	393 ...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	394 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	395 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	396 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	397
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	398 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	399
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	400 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	401 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	402 ...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	403 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	404 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	405
22923 a5eeb288e020 Update to use the new \csimplemacro macro Fred Drake <fdrake@acm.org> parents: 20460 diff changeset	406 The
a5eeb288e020 Update to use the new \csimplemacro macro Fred Drake <fdrake@acm.org> parents: 20460 diff changeset	407 \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	408 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	409 \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	410 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	411 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	412 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	413
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	414 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	415 following code:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	416
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	417 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	418 PyThreadState *_save;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	419
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	420 _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	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_RestoreThread(_save);
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	423 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	424
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	425 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	426 as follows:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	427
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	428 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	429 PyThreadState *_save;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	430
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	431 _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	432 PyEval_ReleaseLock();
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	433 ...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	434 PyEval_AcquireLock();
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	435 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	436 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	437
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	438 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	439 \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	440 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	441 \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	442 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	443 is disabled,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	444 \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	445 \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	446 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	447 \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	448 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	449 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	450 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	451
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	452 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	453 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	454 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	455 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	456 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	457 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	458 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	459
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	460 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	461 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	462 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	463 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	464 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	465 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	466 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	467 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	468 structure.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	469
34452 ad126054ade5 Clean up discussion of new C thread idiom Fred Drake <fdrake@acm.org> parents: 33715 diff changeset	470 Beginning with version 2.3, threads can now take advantage of the
ad126054ade5 Clean up discussion of new C thread idiom Fred Drake <fdrake@acm.org> parents: 33715 diff changeset	471 \cfunction{PyGILState_*()} functions to do all of the above
ad126054ade5 Clean up discussion of new C thread idiom Fred Drake <fdrake@acm.org> parents: 33715 diff changeset	472 automatically. The typical idiom for calling into Python from a C
ad126054ade5 Clean up discussion of new C thread idiom Fred Drake <fdrake@acm.org> parents: 33715 diff changeset	473 thread is now:
28133 9ca4a67b9973 Commit MvL's doc patch for SF bug #221327. This adds an example of Guido van Rossum <guido@python.org> parents: 27798 diff changeset	474
9ca4a67b9973 Commit MvL's doc patch for SF bug #221327. This adds an example of Guido van Rossum <guido@python.org> parents: 27798 diff changeset	475 \begin{verbatim}
32574 228323895271 Replace example with simpler alternative using PyGILState_{Ensure,Require). Can someone please confirm this change is OK? Andrew M. Kuchling <amk@amk.ca> parents: 32573 diff changeset	476 PyGILState_STATE gstate;
228323895271 Replace example with simpler alternative using PyGILState_{Ensure,Require). Can someone please confirm this change is OK? Andrew M. Kuchling <amk@amk.ca> parents: 32573 diff changeset	477 gstate = PyGILState_Ensure();
28133 9ca4a67b9973 Commit MvL's doc patch for SF bug #221327. This adds an example of Guido van Rossum <guido@python.org> parents: 27798 diff changeset	478
9ca4a67b9973 Commit MvL's doc patch for SF bug #221327. This adds an example of Guido van Rossum <guido@python.org> parents: 27798 diff changeset	479 /* Perform Python actions here. */
9ca4a67b9973 Commit MvL's doc patch for SF bug #221327. This adds an example of Guido van Rossum <guido@python.org> parents: 27798 diff changeset	480 result = CallSomeFunction();
9ca4a67b9973 Commit MvL's doc patch for SF bug #221327. This adds an example of Guido van Rossum <guido@python.org> parents: 27798 diff changeset	481 /* evaluate result */
9ca4a67b9973 Commit MvL's doc patch for SF bug #221327. This adds an example of Guido van Rossum <guido@python.org> parents: 27798 diff changeset	482
9ca4a67b9973 Commit MvL's doc patch for SF bug #221327. This adds an example of Guido van Rossum <guido@python.org> parents: 27798 diff changeset	483 /* Release the thread. No Python API allowed beyond this point. */
32574 228323895271 Replace example with simpler alternative using PyGILState_{Ensure,Require). Can someone please confirm this change is OK? Andrew M. Kuchling <amk@amk.ca> parents: 32573 diff changeset	484 PyGILState_Release(gstate);
28133 9ca4a67b9973 Commit MvL's doc patch for SF bug #221327. This adds an example of Guido van Rossum <guido@python.org> parents: 27798 diff changeset	485 \end{verbatim}
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	486
35114 585059de2b40 fix some silly whitespace stuff (must have hit M-q or something?) Michael W. Hudson <mwh@python.net> parents: 34586 diff changeset	487 Note that the \cfunction{PyGILState_*()} functions assume there is
585059de2b40 fix some silly whitespace stuff (must have hit M-q or something?) Michael W. Hudson <mwh@python.net> parents: 34586 diff changeset	488 only one global interpreter (created automatically by
34452 ad126054ade5 Clean up discussion of new C thread idiom Fred Drake <fdrake@acm.org> parents: 33715 diff changeset	489 \cfunction{Py_Initialize()}). Python still supports the creation of
35114 585059de2b40 fix some silly whitespace stuff (must have hit M-q or something?) Michael W. Hudson <mwh@python.net> parents: 34586 diff changeset	490 additional interpreters (using \cfunction{Py_NewInterpreter()}), but
34452 ad126054ade5 Clean up discussion of new C thread idiom Fred Drake <fdrake@acm.org> parents: 33715 diff changeset	491 mixing multiple interpreters and the \cfunction{PyGILState_*()} API is
ad126054ade5 Clean up discussion of new C thread idiom Fred Drake <fdrake@acm.org> parents: 33715 diff changeset	492 unsupported.
ad126054ade5 Clean up discussion of new C thread idiom Fred Drake <fdrake@acm.org> parents: 33715 diff changeset	493
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	494 \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	495 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	496 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	497 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	498 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	499
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	500 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	501 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	502 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	503 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	504 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	505
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	506 \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	507 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	508 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	509 *}\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	510 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	511
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	512 \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	513 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	514 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	515 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	516 \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	517 \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	518 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	519 \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	520 \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	521
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	522 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	523 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	524 \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	525
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	526 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	527 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	528 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	529 Therefore, the lock is not created initially. This situation is
33715 a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick Tim Peters <tim.peters@gmail.com> parents: 33189 diff changeset	530 equivalent to having acquired the lock: when there is only a single
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	531 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	532 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	533 \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	534 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	535 yet, it calls \cfunction{PyEval_InitThreads()}. When this call
33715 a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick Tim Peters <tim.peters@gmail.com> parents: 33189 diff changeset	536 returns, it is guaranteed that the lock has been created and that the
a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick Tim Peters <tim.peters@gmail.com> parents: 33189 diff changeset	537 calling thread has acquired it.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	538
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	539 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	540 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	541
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	542 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	543 compile time.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	544 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	545
33715 a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick Tim Peters <tim.peters@gmail.com> parents: 33189 diff changeset	546 \begin{cfuncdesc}{int}{PyEval_ThreadsInitialized}{}
a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick Tim Peters <tim.peters@gmail.com> parents: 33189 diff changeset	547 Returns a non-zero value if \cfunction{PyEval_InitThreads()} has been
a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick Tim Peters <tim.peters@gmail.com> parents: 33189 diff changeset	548 called. This function can be called without holding the lock, and
a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick Tim Peters <tim.peters@gmail.com> parents: 33189 diff changeset	549 therefore can be used to avoid calls to the locking API when running
a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick Tim Peters <tim.peters@gmail.com> parents: 33189 diff changeset	550 single-threaded. This function is not available when thread support
a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick Tim Peters <tim.peters@gmail.com> parents: 33189 diff changeset	551 is disabled at compile time. \versionadded{2.4}
a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick Tim Peters <tim.peters@gmail.com> parents: 33189 diff changeset	552 \end{cfuncdesc}
a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick Tim Peters <tim.peters@gmail.com> parents: 33189 diff changeset	553
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	554 \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	555 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	556 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	557 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	558 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	559 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	560
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	561 \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	562 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	563 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	564 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	565 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	566
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	567 \begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate}
31679 da78b96b6aab Minor grammatical fixes. Brett Cannon <bcannon@gmail.com> parents: 31678 diff changeset	568 Acquire the global interpreter lock and set the current thread
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	569 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	570 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	571 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	572 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	573 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	574
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	575 \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	576 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	577 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	578 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	579 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	580 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	581 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	582 compile time.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	583 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	584
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	585 \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	586 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	587 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	588 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	589 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	590 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	591 compile time.)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	592 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	593
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	594 \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	595 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	596 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	597 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	598 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	599 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	600 compile time.)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	601 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	602
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	603 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	604 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	605
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	606 \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	607 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	608 \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	609 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	610 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	611 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	612 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	613 \end{csimplemacrodesc}
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{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	616 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	617 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	618 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	619 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	620 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	621 \end{csimplemacrodesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	622
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	623 \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	624 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	625 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	626 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	627 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	628 \end{csimplemacrodesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	629
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	630 \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	631 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	632 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	633 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	634 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	635 \end{csimplemacrodesc}
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 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	638 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	639 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	640
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	641 \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	642 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	643 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	644 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	645 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	646
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	647 \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	648 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	649 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	650 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	651
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	652 \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	653 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	654 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	655 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	656 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	657
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	658 \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	659 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	660 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	661 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	662 \end{cfuncdesc}
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 \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	665 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	666 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	667 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	668
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	669 \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	670 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	671 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	672 \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	673 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	674
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	675 \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	676 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	677 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	678 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	679 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	680
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	681 \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	682 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	683 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	684 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	685 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	686
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	687 \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	688 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	689 state information. Each extension should use a unique key to use to
28616 4f0b7acffc7d - pythunrun.c, Py_Finalize(): move the call to _Py_PrintReferences() Guido van Rossum <guido@python.org> parents: 28133 diff changeset	690 store state in the dictionary. It is okay to call this function
4f0b7acffc7d - pythunrun.c, Py_Finalize(): move the call to _Py_PrintReferences() Guido van Rossum <guido@python.org> parents: 28133 diff changeset	691 when no current thread state is available.
4f0b7acffc7d - pythunrun.c, Py_Finalize(): move the call to _Py_PrintReferences() Guido van Rossum <guido@python.org> parents: 28133 diff changeset	692 If this function returns \NULL, no exception has been raised and the
4f0b7acffc7d - pythunrun.c, Py_Finalize(): move the call to _Py_PrintReferences() Guido van Rossum <guido@python.org> parents: 28133 diff changeset	693 caller should assume no current thread state is available.
4f0b7acffc7d - pythunrun.c, Py_Finalize(): move the call to _Py_PrintReferences() Guido van Rossum <guido@python.org> parents: 28133 diff changeset	694 \versionchanged[Previously this could only be called when a current
30360 be9582734b56 fix \NULL with following space and no {} Fred Drake <fdrake@acm.org> parents: 30134 diff changeset	695 thread is active, and \NULL{} meant that an exception was raised]{2.3}
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	696 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	697
29649 8bd2580e0155 Document PyThreadState_SetAsyncExc(). Fred Drake <fdrake@acm.org> parents: 28616 diff changeset	698 \begin{cfuncdesc}{int}{PyThreadState_SetAsyncExc}{long id, PyObject *exc}
39431 de9e1a5dca93 Followup to bug #1069160. Tim Peters <tim.peters@gmail.com> parents: 36767 diff changeset	699 Asynchronously raise an exception in a thread.
29649 8bd2580e0155 Document PyThreadState_SetAsyncExc(). Fred Drake <fdrake@acm.org> parents: 28616 diff changeset	700 The \var{id} argument is the thread id of the target thread;
8bd2580e0155 Document PyThreadState_SetAsyncExc(). Fred Drake <fdrake@acm.org> parents: 28616 diff changeset	701 \var{exc} is the exception object to be raised.
8bd2580e0155 Document PyThreadState_SetAsyncExc(). Fred Drake <fdrake@acm.org> parents: 28616 diff changeset	702 This function does not steal any references to \var{exc}.
39431 de9e1a5dca93 Followup to bug #1069160. Tim Peters <tim.peters@gmail.com> parents: 36767 diff changeset	703 To prevent naive misuse, you must write your own C extension
de9e1a5dca93 Followup to bug #1069160. Tim Peters <tim.peters@gmail.com> parents: 36767 diff changeset	704 to call this. Must be called with the GIL held.
de9e1a5dca93 Followup to bug #1069160. Tim Peters <tim.peters@gmail.com> parents: 36767 diff changeset	705 Returns the number of thread states modified; this is normally one, but
de9e1a5dca93 Followup to bug #1069160. Tim Peters <tim.peters@gmail.com> parents: 36767 diff changeset	706 will be zero if the thread id isn't found. If \var{exc} is
de9e1a5dca93 Followup to bug #1069160. Tim Peters <tim.peters@gmail.com> parents: 36767 diff changeset	707 \constant{NULL}, the pending exception (if any) for the thread is cleared.
29649 8bd2580e0155 Document PyThreadState_SetAsyncExc(). Fred Drake <fdrake@acm.org> parents: 28616 diff changeset	708 This raises no exceptions.
8bd2580e0155 Document PyThreadState_SetAsyncExc(). Fred Drake <fdrake@acm.org> parents: 28616 diff changeset	709 \versionadded{2.3}
8bd2580e0155 Document PyThreadState_SetAsyncExc(). Fred Drake <fdrake@acm.org> parents: 28616 diff changeset	710 \end{cfuncdesc}
8bd2580e0155 Document PyThreadState_SetAsyncExc(). Fred Drake <fdrake@acm.org> parents: 28616 diff changeset	711
32573 153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	712 \begin{cfuncdesc}{PyGILState_STATE}{PyGILState_Ensure}{}
35114 585059de2b40 fix some silly whitespace stuff (must have hit M-q or something?) Michael W. Hudson <mwh@python.net> parents: 34586 diff changeset	713 Ensure that the current thread is ready to call the Python C API
585059de2b40 fix some silly whitespace stuff (must have hit M-q or something?) Michael W. Hudson <mwh@python.net> parents: 34586 diff changeset	714 regardless of the current state of Python, or of its thread lock.
585059de2b40 fix some silly whitespace stuff (must have hit M-q or something?) Michael W. Hudson <mwh@python.net> parents: 34586 diff changeset	715 This may be called as many times as desired by a thread as long as
585059de2b40 fix some silly whitespace stuff (must have hit M-q or something?) Michael W. Hudson <mwh@python.net> parents: 34586 diff changeset	716 each call is matched with a call to \cfunction{PyGILState_Release()}.
585059de2b40 fix some silly whitespace stuff (must have hit M-q or something?) Michael W. Hudson <mwh@python.net> parents: 34586 diff changeset	717 In general, other thread-related APIs may be used between
585059de2b40 fix some silly whitespace stuff (must have hit M-q or something?) Michael W. Hudson <mwh@python.net> parents: 34586 diff changeset	718 \cfunction{PyGILState_Ensure()} and \cfunction{PyGILState_Release()}
585059de2b40 fix some silly whitespace stuff (must have hit M-q or something?) Michael W. Hudson <mwh@python.net> parents: 34586 diff changeset	719 calls as long as the thread state is restored to its previous state
585059de2b40 fix some silly whitespace stuff (must have hit M-q or something?) Michael W. Hudson <mwh@python.net> parents: 34586 diff changeset	720 before the Release(). For example, normal usage of the
585059de2b40 fix some silly whitespace stuff (must have hit M-q or something?) Michael W. Hudson <mwh@python.net> parents: 34586 diff changeset	721 \csimplemacro{Py_BEGIN_ALLOW_THREADS} and
585059de2b40 fix some silly whitespace stuff (must have hit M-q or something?) Michael W. Hudson <mwh@python.net> parents: 34586 diff changeset	722 \csimplemacro{Py_END_ALLOW_THREADS} macros is acceptable.
32573 153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	723
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	724 The return value is an opaque "handle" to the thread state when
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	725 \cfunction{PyGILState_Acquire()} was called, and must be passed to
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	726 \cfunction{PyGILState_Release()} to ensure Python is left in the same
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	727 state. Even though recursive calls are allowed, these handles
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	728 \emph{cannot} be shared - each unique call to
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	729 \cfunction{PyGILState_Ensure} must save the handle for its call to
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	730 \cfunction{PyGILState_Release}.
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	731
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	732 When the function returns, the current thread will hold the GIL.
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	733 Failure is a fatal error.
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	734 \versionadded{2.3}
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	735 \end{cfuncdesc}
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	736
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	737 \begin{cfuncdesc}{void}{PyGILState_Release}{PyGILState_STATE}
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	738 Release any resources previously acquired. After this call, Python's
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	739 state will be the same as it was prior to the corresponding
32574 228323895271 Replace example with simpler alternative using PyGILState_{Ensure,Require). Can someone please confirm this change is OK? Andrew M. Kuchling <amk@amk.ca> parents: 32573 diff changeset	740 \cfunction{PyGILState_Ensure} call (but generally this state will be
228323895271 Replace example with simpler alternative using PyGILState_{Ensure,Require). Can someone please confirm this change is OK? Andrew M. Kuchling <amk@amk.ca> parents: 32573 diff changeset	741 unknown to the caller, hence the use of the GILState API.)
32573 153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	742
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	743 Every call to \cfunction{PyGILState_Ensure()} must be matched by a call to
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	744 \cfunction{PyGILState_Release()} on the same thread.
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	745 \versionadded{2.3}
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	746 \end{cfuncdesc}
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.) Andrew M. Kuchling <amk@amk.ca> parents: 31796 diff changeset	747
20390 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 \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	750
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 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	754 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	755 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	756
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	757 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	758 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	759 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	760 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	761 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	762 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	763 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	764 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	765 previous versions.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	766
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	767 \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	768 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	769 PyObject *arg)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	770 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	771 \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	772 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	773 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	774 event pertains, \var{what} is one of the constants
31796 1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	775 \constant{PyTrace_CALL}, \constant{PyTrace_EXCEPTION},
1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	776 \constant{PyTrace_LINE}, \constant{PyTrace_RETURN},
1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	777 \constant{PyTrace_C_CALL}, \constant{PyTrace_C_EXCEPTION},
1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	778 or \constant{PyTrace_C_RETURN}, and \var{arg}
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	779 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	780
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	781 \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	782 \lineii{PyTrace_CALL}{Always \NULL.}
31796 1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	783 \lineii{PyTrace_EXCEPTION}{Exception information as returned by
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	784 \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	785 \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	786 \lineii{PyTrace_RETURN}{Value being returned to the caller.}
31796 1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	787 \lineii{PyTrace_C_CALL}{Name of function being called.}
1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	788 \lineii{PyTrace_C_EXCEPTION}{Always \NULL.}
1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	789 \lineii{PyTrace_C_RETURN}{Always \NULL.}
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	790 \end{tableii}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	791 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	792
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	793 \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	794 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	795 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	796 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	797 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	798 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	799 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	800
31796 1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	801 \begin{cvardesc}{int}{PyTrace_EXCEPTION}
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	802 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	803 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	804 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	805 processed after which the exception becomes set within the frame
30715 c12d4f1853bc Patch #821093: Fix various typos. Martin v. Löwis <martin@v.loewis.de> parents: 30360 diff changeset	806 being executed. The effect of this is that as exception propagation
20460 ffbf94fd9cef Update the description of PyTrace_EXCEPT. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	807 causes the Python stack to unwind, the callback is called upon
26558 701b797bbdc8 Typo: propogate -> propagate Thomas Heller <theller@ctypes.org> parents: 25709 diff changeset	808 return to each frame as the exception propagates. Only trace
20460 ffbf94fd9cef Update the description of PyTrace_EXCEPT. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	809 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	810 profiler.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	811 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	812
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	813 \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	814 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	815 (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	816 reported.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	817 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	818
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	819 \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	820 The value for the \var{what} parameter to \ctype{Py_tracefunc}
30715 c12d4f1853bc Patch #821093: Fix various typos. Martin v. Löwis <martin@v.loewis.de> parents: 30360 diff changeset	821 functions when a call is returning without propagating an exception.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	822 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	823
31796 1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	824 \begin{cvardesc}{int}{PyTrace_C_CALL}
1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	825 The value for the \var{what} parameter to \ctype{Py_tracefunc}
1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	826 functions when a C function is about to be called.
1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	827 \end{cvardesc}
1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	828
1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	829 \begin{cvardesc}{int}{PyTrace_C_EXCEPTION}
1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	830 The value for the \var{what} parameter to \ctype{Py_tracefunc}
1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	831 functions when a C function has thrown an exception.
1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	832 \end{cvardesc}
1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	833
1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	834 \begin{cvardesc}{int}{PyTrace_C_RETURN}
1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	835 The value for the \var{what} parameter to \ctype{Py_tracefunc}
1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	836 functions when a C function has returned.
1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	837 \end{cvardesc}
1c117dbb2def Enable the profiling of C functions (builtins and extensions) Nicholas Bastin <nick.bastin@gmail.com> parents: 31679 diff changeset	838
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	839 \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	840 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	841 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	842 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	843 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	844 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	845 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	846 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	847
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	848 \begin{cfuncdesc}{void}{PyEval_SetTrace}{Py_tracefunc func, PyObject *obj}
30134 523c3d61dbdd SF patch#786531 'the the' typo. Contributed by George Yoshida Raymond Hettinger <python@rcn.com> parents: 29750 diff changeset	849 Set the tracing function to \var{func}. This is similar to
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	850 \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	851 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	852 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	853
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	854
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	855 \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	856 \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	857
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	858 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	859 tools.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	860
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	861 \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	862 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	863 such objects.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	864 \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	865 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	866
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	867 \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	868 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	869 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	870 \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	871 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	872
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	873 \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	874 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	875 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	876 \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	877 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	878
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	879 \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	880 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	881 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	882 object.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	883 \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	884 \end{cfuncdesc}

Mercurial > cpython-lru_cache-weakref

annotate Doc/api/init.tex @ 39940:dfd809dcf680 2.5