Mercurial > cpython-lru_cache-weakref

annotate Doc/api/init.tex @ 32975:9b188158181f legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Typo fix; use 'in-place' instead of 'inplace'
author Andrew M. Kuchling <amk@amk.ca>
date Fri, 06 Aug 2004 18:55:09 +0000
parents 511ffc62b298
children de804edf8bcd
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1 \chapter{Initialization, Finalization, and Threads
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
2 \label{initialization}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
3
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
4 \begin{cfuncdesc}{void}{Py_Initialize}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
5 Initialize the Python interpreter. In an application embedding
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
6 Python, this should be called before using any other Python/C API
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
7 functions; with the exception of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
8 \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()},
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
9 \cfunction{PyEval_InitThreads()}\ttindex{PyEval_InitThreads()},
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
10 \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()},
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
11 and \cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
12 This initializes the table of loaded modules (\code{sys.modules}),
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
13 and\withsubitem{(in module sys)}{\ttindex{modules}\ttindex{path}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
14 creates the fundamental modules
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
15 \module{__builtin__}\refbimodindex{__builtin__},
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
16 \module{__main__}\refbimodindex{__main__} and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
17 \module{sys}\refbimodindex{sys}. It also initializes the module
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
18 search\indexiii{module}{search}{path} path (\code{sys.path}).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
19 It does not set \code{sys.argv}; use
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
20 \cfunction{PySys_SetArgv()}\ttindex{PySys_SetArgv()} for that. This
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
21 is a no-op when called for a second time (without calling
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
22 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} first). There is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
23 no return value; it is a fatal error if the initialization fails.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
24 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
25
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
26 \begin{cfuncdesc}{int}{Py_IsInitialized}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
27 Return true (nonzero) when the Python interpreter has been
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
28 initialized, false (zero) if not. After \cfunction{Py_Finalize()}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
29 is called, this returns false until \cfunction{Py_Initialize()} is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
30 called again.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
31 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
32
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
33 \begin{cfuncdesc}{void}{Py_Finalize}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
34 Undo all initializations made by \cfunction{Py_Initialize()} and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
35 subsequent use of Python/C API functions, and destroy all
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
36 sub-interpreters (see \cfunction{Py_NewInterpreter()} below) that
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
37 were created and not yet destroyed since the last call to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
38 \cfunction{Py_Initialize()}. Ideally, this frees all memory
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
39 allocated by the Python interpreter. This is a no-op when called
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
40 for a second time (without calling \cfunction{Py_Initialize()} again
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
41 first). There is no return value; errors during finalization are
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
42 ignored.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
43
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
44 This function is provided for a number of reasons. An embedding
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
45 application might want to restart Python without having to restart
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
46 the application itself. An application that has loaded the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
47 interpreter from a dynamically loadable library (or DLL) might want
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
48 to free all memory allocated by Python before unloading the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
49 DLL. During a hunt for memory leaks in an application a developer
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
50 might want to free all memory allocated by Python before exiting
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
51 from the application.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
52
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
53 \strong{Bugs and caveats:} The destruction of modules and objects in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
54 modules is done in random order; this may cause destructors
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
55 (\method{__del__()} methods) to fail when they depend on other
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
56 objects (even functions) or modules. Dynamically loaded extension
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
57 modules loaded by Python are not unloaded. Small amounts of memory
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
58 allocated by the Python interpreter may not be freed (if you find a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
59 leak, please report it). Memory tied up in circular references
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
60 between objects is not freed. Some memory allocated by extension
27798
e62099c65a3c A typo, and desist from inaccurately describing some things as lists.
Michael W. Hudson <mwh@python.net>
parents: 26558
diff changeset
61 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
62 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
63 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
64 \cfunction{Py_Finalize()} more than once.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
65 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
66
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
67 \begin{cfuncdesc}{PyThreadState*}{Py_NewInterpreter}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
68 Create a new sub-interpreter. This is an (almost) totally separate
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
69 environment for the execution of Python code. In particular, the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
70 new interpreter has separate, independent versions of all imported
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
71 modules, including the fundamental modules
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
72 \module{__builtin__}\refbimodindex{__builtin__},
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
73 \module{__main__}\refbimodindex{__main__} and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
74 \module{sys}\refbimodindex{sys}. The table of loaded modules
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
75 (\code{sys.modules}) and the module search path (\code{sys.path})
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
76 are also separate. The new environment has no \code{sys.argv}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
77 variable. It has new standard I/O stream file objects
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
78 \code{sys.stdin}, \code{sys.stdout} and \code{sys.stderr} (however
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
79 these refer to the same underlying \ctype{FILE} structures in the C
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
80 library).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
81 \withsubitem{(in module sys)}{
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
82 \ttindex{stdout}\ttindex{stderr}\ttindex{stdin}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
83
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
84 The return value points to the first thread state created in the new
31679
da78b96b6aab Minor grammatical fixes.
Brett Cannon <bcannon@gmail.com>
parents: 31678
diff changeset
85 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
86 state. Note that no actual thread is created; see the discussion of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
87 thread states below. If creation of the new interpreter is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
88 unsuccessful, \NULL{} is returned; no exception is set since the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
89 exception state is stored in the current thread state and there may
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
90 not be a current thread state. (Like all other Python/C API
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
91 functions, the global interpreter lock must be held before calling
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
92 this function and is still held when it returns; however, unlike
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
93 most other Python/C API functions, there needn't be a current thread
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
94 state on entry.)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
95
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
96 Extension modules are shared between (sub-)interpreters as follows:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
97 the first time a particular extension is imported, it is initialized
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
98 normally, and a (shallow) copy of its module's dictionary is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
99 squirreled away. When the same extension is imported by another
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
100 (sub-)interpreter, a new module is initialized and filled with the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
101 contents of this copy; the extension's \code{init} function is not
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
102 called. Note that this is different from what happens when an
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
103 extension is imported after the interpreter has been completely
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
104 re-initialized by calling
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
105 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
106 \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}; in that case,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
107 the extension's \code{init\var{module}} function \emph{is} called
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
108 again.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
109
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
110 \strong{Bugs and caveats:} Because sub-interpreters (and the main
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
111 interpreter) are part of the same process, the insulation between
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
112 them isn't perfect --- for example, using low-level file operations
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
113 like \withsubitem{(in module os)}{\ttindex{close()}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
114 \function{os.close()} they can (accidentally or maliciously) affect
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
115 each other's open files. Because of the way extensions are shared
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
116 between (sub-)interpreters, some extensions may not work properly;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
117 this is especially likely when the extension makes use of (static)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
118 global variables, or when the extension manipulates its module's
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
119 dictionary after its initialization. It is possible to insert
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
120 objects created in one sub-interpreter into a namespace of another
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
121 sub-interpreter; this should be done with great care to avoid
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
122 sharing user-defined functions, methods, instances or classes
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
123 between sub-interpreters, since import operations executed by such
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
124 objects may affect the wrong (sub-)interpreter's dictionary of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
125 loaded modules. (XXX This is a hard-to-fix bug that will be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
126 addressed in a future release.)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
127 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
128
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
129 \begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
130 Destroy the (sub-)interpreter represented by the given thread state.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
131 The given thread state must be the current thread state. See the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
132 discussion of thread states below. When the call returns, the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
133 current thread state is \NULL. All thread states associated with
31678
c0a542a1fc1c Extremely minor typo fixed.
Brett Cannon <bcannon@gmail.com>
parents: 30715
diff changeset
134 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
135 be held before calling this function and is still held when it
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
136 returns.) \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} will
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
137 destroy all sub-interpreters that haven't been explicitly destroyed
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
138 at that point.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
139 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
140
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
141 \begin{cfuncdesc}{void}{Py_SetProgramName}{char *name}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
142 This function should be called before
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
143 \cfunction{Py_Initialize()}\ttindex{Py_Initialize()} is called
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
144 for the first time, if it is called at all. It tells the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
145 interpreter the value of the \code{argv[0]} argument to the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
146 \cfunction{main()}\ttindex{main()} function of the program. This is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
147 used by \cfunction{Py_GetPath()}\ttindex{Py_GetPath()} and some
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
148 other functions below to find the Python run-time libraries relative
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
149 to the interpreter executable. The default value is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
150 \code{'python'}. The argument should point to a zero-terminated
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
151 character string in static storage whose contents will not change
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
152 for the duration of the program's execution. No code in the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
153 interpreter will change the contents of this storage.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
154 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
155
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
156 \begin{cfuncdesc}{char*}{Py_GetProgramName}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
157 Return the program name set with
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
158 \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()}, or the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
159 default. The returned string points into static storage; the caller
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
160 should not modify its value.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
161 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
162
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
163 \begin{cfuncdesc}{char*}{Py_GetPrefix}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
164 Return the \emph{prefix} for installed platform-independent files.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
165 This is derived through a number of complicated rules from the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
166 program name set with \cfunction{Py_SetProgramName()} and some
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
167 environment variables; for example, if the program name is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
168 \code{'/usr/local/bin/python'}, the prefix is \code{'/usr/local'}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
169 The returned string points into static storage; the caller should
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
170 not modify its value. This corresponds to the \makevar{prefix}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
171 variable in the top-level \file{Makefile} and the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
172 \longprogramopt{prefix} argument to the \program{configure} script
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
173 at build time. The value is available to Python code as
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
174 \code{sys.prefix}. It is only useful on \UNIX. See also the next
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
175 function.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
176 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
177
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
178 \begin{cfuncdesc}{char*}{Py_GetExecPrefix}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
179 Return the \emph{exec-prefix} for installed
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
180 platform-\emph{de}pendent files. This is derived through a number
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
181 of complicated rules from the program name set with
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
182 \cfunction{Py_SetProgramName()} and some environment variables; for
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
183 example, if the program name is \code{'/usr/local/bin/python'}, the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
184 exec-prefix is \code{'/usr/local'}. The returned string points into
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
185 static storage; the caller should not modify its value. This
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
186 corresponds to the \makevar{exec_prefix} variable in the top-level
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
187 \file{Makefile} and the \longprogramopt{exec-prefix} argument to the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
188 \program{configure} script at build time. The value is available
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
189 to Python code as \code{sys.exec_prefix}. It is only useful on
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
190 \UNIX.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
191
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
192 Background: The exec-prefix differs from the prefix when platform
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
193 dependent files (such as executables and shared libraries) are
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
194 installed in a different directory tree. In a typical installation,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
195 platform dependent files may be installed in the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
196 \file{/usr/local/plat} subtree while platform independent may be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
197 installed in \file{/usr/local}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
198
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
199 Generally speaking, a platform is a combination of hardware and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
200 software families, e.g. Sparc machines running the Solaris 2.x
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
201 operating system are considered the same platform, but Intel
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
202 machines running Solaris 2.x are another platform, and Intel
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
203 machines running Linux are yet another platform. Different major
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
204 revisions of the same operating system generally also form different
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
205 platforms. Non-\UNIX{} operating systems are a different story; the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
206 installation strategies on those systems are so different that the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
207 prefix and exec-prefix are meaningless, and set to the empty string.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
208 Note that compiled Python bytecode files are platform independent
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
209 (but not independent from the Python version by which they were
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
210 compiled!).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
211
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
212 System administrators will know how to configure the \program{mount}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
213 or \program{automount} programs to share \file{/usr/local} between
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
214 platforms while having \file{/usr/local/plat} be a different
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
215 filesystem for each platform.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
216 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
217
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
218 \begin{cfuncdesc}{char*}{Py_GetProgramFullPath}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
219 Return the full program name of the Python executable; this is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
220 computed as a side-effect of deriving the default module search path
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
221 from the program name (set by
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
222 \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()} above).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
223 The returned string points into static storage; the caller should
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
224 not modify its value. The value is available to Python code as
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
225 \code{sys.executable}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
226 \withsubitem{(in module sys)}{\ttindex{executable}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
227 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
228
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
229 \begin{cfuncdesc}{char*}{Py_GetPath}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
230 \indexiii{module}{search}{path}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
231 Return the default module search path; this is computed from the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
232 program name (set by \cfunction{Py_SetProgramName()} above) and some
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
233 environment variables. The returned string consists of a series of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
234 directory names separated by a platform dependent delimiter
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
235 character. The delimiter character is \character{:} on \UNIX,
25709
1a9f47885260 Remove mentionings of DOS.
Martin v. Löwis <martin@v.loewis.de>
parents: 22923
diff changeset
236 \character{;} on Windows, and \character{\e n} (the \ASCII{}
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
237 newline character) on Macintosh. The returned string points into
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
238 static storage; the caller should not modify its value. The value
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
239 is available to Python code as the list
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
240 \code{sys.path}\withsubitem{(in module sys)}{\ttindex{path}}, which
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
241 may be modified to change the future search path for loaded
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
242 modules.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
243
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
244 % XXX should give the exact rules
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
245 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
246
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
247 \begin{cfuncdesc}{const char*}{Py_GetVersion}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
248 Return the version of this Python interpreter. This is a string
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
249 that looks something like
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
250
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
251 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
252 "1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]"
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
253 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
254
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
255 The first word (up to the first space character) is the current
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
256 Python version; the first three characters are the major and minor
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
257 version separated by a period. The returned string points into
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
258 static storage; the caller should not modify its value. The value
27798
e62099c65a3c A typo, and desist from inaccurately describing some things as lists.
Michael W. Hudson <mwh@python.net>
parents: 26558
diff changeset
259 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
260 \withsubitem{(in module sys)}{\ttindex{version}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
261 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
262
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
263 \begin{cfuncdesc}{const char*}{Py_GetPlatform}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
264 Return the platform identifier for the current platform. On \UNIX,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
265 this is formed from the ``official'' name of the operating system,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
266 converted to lower case, followed by the major revision number;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
267 e.g., for Solaris 2.x, which is also known as SunOS 5.x, the value
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
268 is \code{'sunos5'}. On Macintosh, it is \code{'mac'}. On Windows,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
269 it is \code{'win'}. The returned string points into static storage;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
270 the caller should not modify its value. The value is available to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
271 Python code as \code{sys.platform}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
272 \withsubitem{(in module sys)}{\ttindex{platform}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
273 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
274
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
275 \begin{cfuncdesc}{const char*}{Py_GetCopyright}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
276 Return the official copyright string for the current Python version,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
277 for example
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
278
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
279 \code{'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
280
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
281 The returned string points into static storage; the caller should
27798
e62099c65a3c A typo, and desist from inaccurately describing some things as lists.
Michael W. Hudson <mwh@python.net>
parents: 26558
diff changeset
282 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
283 \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
284 \withsubitem{(in module sys)}{\ttindex{copyright}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
285 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
286
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
287 \begin{cfuncdesc}{const char*}{Py_GetCompiler}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
288 Return an indication of the compiler used to build the current
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
289 Python version, in square brackets, for example:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
290
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
291 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
292 "[GCC 2.7.2.2]"
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
293 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
294
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
295 The returned string points into static storage; the caller should
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
296 not modify its value. The value is available to Python code as part
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
297 of the variable \code{sys.version}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
298 \withsubitem{(in module sys)}{\ttindex{version}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
299 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
300
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
301 \begin{cfuncdesc}{const char*}{Py_GetBuildInfo}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
302 Return information about the sequence number and build date and time
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
303 of the current Python interpreter instance, for example
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
304
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
305 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
306 "#67, Aug 1 1997, 22:34:28"
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
307 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
308
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
309 The returned string points into static storage; the caller should
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
310 not modify its value. The value is available to Python code as part
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
311 of the variable \code{sys.version}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
312 \withsubitem{(in module sys)}{\ttindex{version}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
313 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
314
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
315 \begin{cfuncdesc}{int}{PySys_SetArgv}{int argc, char **argv}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
316 Set \code{sys.argv} based on \var{argc} and \var{argv}. These
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
317 parameters are similar to those passed to the program's
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
318 \cfunction{main()}\ttindex{main()} function with the difference that
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
319 the first entry should refer to the script file to be executed
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
320 rather than the executable hosting the Python interpreter. If there
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
321 isn't a script that will be run, the first entry in \var{argv} can
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
322 be an empty string. If this function fails to initialize
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
323 \code{sys.argv}, a fatal condition is signalled using
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
324 \cfunction{Py_FatalError()}\ttindex{Py_FatalError()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
325 \withsubitem{(in module sys)}{\ttindex{argv}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
326 % XXX impl. doesn't seem consistent in allowing 0/NULL for the params;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
327 % check w/ Guido.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
328 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
329
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
330 % XXX Other PySys thingies (doesn't really belong in this chapter)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
331
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
332 \section{Thread State and the Global Interpreter Lock
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
333 \label{threads}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
334
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
335 \index{global interpreter lock}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
336 \index{interpreter lock}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
337 \index{lock, interpreter}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
338
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
339 The Python interpreter is not fully thread safe. In order to support
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
340 multi-threaded Python programs, there's a global lock that must be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
341 held by the current thread before it can safely access Python objects.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
342 Without the lock, even the simplest operations could cause problems in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
343 a multi-threaded program: for example, when two threads simultaneously
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
344 increment the reference count of the same object, the reference count
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
345 could end up being incremented only once instead of twice.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
346
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
347 Therefore, the rule exists that only the thread that has acquired the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
348 global interpreter lock may operate on Python objects or call Python/C
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
349 API functions. In order to support multi-threaded Python programs,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
350 the interpreter regularly releases and reacquires the lock --- by
29750
b86446f0350f Correct documentation of check interval - it's 100 by default, not 10 any
Skip Montanaro <skip@pobox.com>
parents: 29649
diff changeset
351 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
352 \withsubitem{(in module sys)}{\ttindex{setcheckinterval()}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
353 \function{sys.setcheckinterval()}). The lock is also released and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
354 reacquired around potentially blocking I/O operations like reading or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
355 writing a file, so that other threads can run while the thread that
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
356 requests the I/O is waiting for the I/O operation to complete.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
357
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
358 The Python interpreter needs to keep some bookkeeping information
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
359 separate per thread --- for this it uses a data structure called
32575
511ffc62b298 Remove a few elderly sentences
Andrew M. Kuchling <amk@amk.ca>
parents: 32574
diff changeset
360 \ctype{PyThreadState}\ttindex{PyThreadState}. There's one global
511ffc62b298 Remove a few elderly sentences
Andrew M. Kuchling <amk@amk.ca>
parents: 32574
diff changeset
361 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
362 \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
363 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
364 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
365 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
366 manipulated explicitly.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
367
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
368 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
369 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
370
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
371 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
372 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
373 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
374 ...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
375 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
376 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
377 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
378
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
379 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
380
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
381 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
382 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
383 ...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
384 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
385 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
386
22923
a5eeb288e020 Update to use the new \csimplemacro macro
Fred Drake <fdrake@acm.org>
parents: 20460
diff changeset
387 The
a5eeb288e020 Update to use the new \csimplemacro macro
Fred Drake <fdrake@acm.org>
parents: 20460
diff changeset
388 \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
389 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
390 \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
391 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
392 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
393 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
394
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
395 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
396 following code:
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 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
399 PyThreadState *_save;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
400
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
401 _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
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 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
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
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
406 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
407 as follows:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
408
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
409 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
410 PyThreadState *_save;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
411
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
412 _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
413 PyEval_ReleaseLock();
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
414 ...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
415 PyEval_AcquireLock();
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
416 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
417 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
418
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
419 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
420 \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
421 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
422 \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
423 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
424 is disabled,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
425 \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
426 \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
427 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
428 \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
429 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
430 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
431 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
432
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
433 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
434 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
435 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
436 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
437 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
438 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
439 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
440
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
441 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
442 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
443 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
444 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
445 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
446 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
447 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
448 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
449 structure.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
450
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
451 When creating a thread data structure, you need to provide an
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
452 interpreter state data structure. The interpreter state data
31679
da78b96b6aab Minor grammatical fixes.
Brett Cannon <bcannon@gmail.com>
parents: 31678
diff changeset
453 structure holds global data that is shared by all threads in an
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
454 interpreter, for example the module administration
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
455 (\code{sys.modules}). Depending on your needs, you can either create
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
456 a new interpreter state data structure, or share the interpreter state
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
457 data structure used by the Python main thread (to access the latter,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
458 you must obtain the thread state and access its \member{interp} member;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
459 this must be done by a thread that is created by Python or by the main
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
460 thread after Python is initialized).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
461
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
462 Assuming you have access to an interpreter object, the typical idiom
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
463 for calling into Python from a C thread is
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
464
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
465 \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
466 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
467 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
468
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
469 /* 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
470 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
471 /* 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
472
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
473 /* 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
474 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
475 \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
476
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
477 \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
478 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
479 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
480 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
481 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
482
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
483 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
484 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
485 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
486 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
487 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
488
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
489 \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
490 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
491 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
492 *}\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
493 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
494
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
495 \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
496 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
497 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
498 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
499 \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
500 \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
501 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
502 \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
503 \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
504
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
505 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
506 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
507 \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
508
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
509 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
510 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
511 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
512 Therefore, the lock is not created initially. This situation is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
513 equivalent to having acquired the lock: when there is only a single
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
514 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
515 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
516 \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
517 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
518 yet, it calls \cfunction{PyEval_InitThreads()}. When this call
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
519 returns, it is guaranteed that the lock has been created and that it
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
520 has acquired it.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
521
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
522 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
523 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
524
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
525 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
526 compile time.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
527 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
528
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
529 \begin{cfuncdesc}{void}{PyEval_AcquireLock}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
530 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
531 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
532 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
533 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
534 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
535
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
536 \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
537 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
538 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
539 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
540 \end{cfuncdesc}
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 \begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate}
31679
da78b96b6aab Minor grammatical fixes.
Brett Cannon <bcannon@gmail.com>
parents: 31678
diff changeset
543 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
544 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
545 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
546 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
547 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
548 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
549
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
550 \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
551 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
552 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
553 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
554 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
555 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
556 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
557 compile time.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
558 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
559
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
560 \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
561 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
562 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
563 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
564 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
565 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
566 compile time.)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
567 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
568
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
569 \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
570 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
571 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
572 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
573 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
574 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
575 compile time.)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
576 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
577
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
578 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
579 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
580
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
581 \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
582 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
583 \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
584 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
585 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
586 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
587 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
588 \end{csimplemacrodesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
589
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
590 \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
591 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
592 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
593 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
594 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
595 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
596 \end{csimplemacrodesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
597
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
598 \begin{csimplemacrodesc}{Py_BLOCK_THREADS}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
599 This macro expands to \samp{PyEval_RestoreThread(_save);}: it is
22923
a5eeb288e020 Update to use the new \csimplemacro macro
Fred Drake <fdrake@acm.org>
parents: 20460
diff changeset
600 equivalent to \csimplemacro{Py_END_ALLOW_THREADS} without the
a5eeb288e020 Update to use the new \csimplemacro macro
Fred Drake <fdrake@acm.org>
parents: 20460
diff changeset
601 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
602 compile time.
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
603 \end{csimplemacrodesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
604
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
605 \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
606 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
607 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
608 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
609 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
610 \end{csimplemacrodesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
611
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
612 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
613 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
614 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
615
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
616 \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
617 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
618 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
619 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
620 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
621
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
622 \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
623 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
624 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
625 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
626
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
627 \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
628 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
629 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
630 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
631 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
632
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
633 \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
634 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
635 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
636 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
637 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
638
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
639 \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
640 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
641 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
642 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
643
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
644 \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
645 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
646 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
647 \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
648 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
649
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
650 \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
651 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
652 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
653 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
654 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
655
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
656 \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
657 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
658 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
659 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
660 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
661
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
662 \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
663 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
664 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
665 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
666 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
667 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
668 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
669 \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
670 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
671 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
672
29649
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
673 \begin{cfuncdesc}{int}{PyThreadState_SetAsyncExc}{long id, PyObject *exc}
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
674 Asynchronously raise an exception in a thread.
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
675 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
676 \var{exc} is the exception object to be raised.
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
677 This function does not steal any references to \var{exc}.
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
678 To prevent naive misuse, you must write your own C extension
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
679 to call this. Must be called with the GIL held.
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
680 Returns the number of thread states modified; if it returns a number
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
681 greater than one, you're in trouble, and you should call it again
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
682 with \var{exc} set to \constant{NULL} to revert the effect.
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
683 This raises no exceptions.
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
684 \versionadded{2.3}
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
685 \end{cfuncdesc}
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
686
32573
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
687 \begin{cfuncdesc}{PyGILState_STATE}{PyGILState_Ensure}{}
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
688 Ensure that the current thread is ready to call the Python
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
689 C API regardless of the current state of Python, or of its
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
690 thread lock. This may be called as many times as desired
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
691 by a thread as long as each call is matched with a call to
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
692 \cfunction{PyGILState_Release()}.
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
693 In general, other thread-related APIs may
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
694 be used between \cfunction{PyGILState_Ensure()} and \cfunction{PyGILState_Release()} calls as long as the
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
695 thread state is restored to its previous state before the Release().
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
696 For example, normal usage of the \csimplemacro{Py_BEGIN_ALLOW_THREADS}
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
697 and \csimplemacro{Py_END_ALLOW_THREADS} macros is acceptable.
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
698
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
699 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
700 \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
701 \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
702 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
703 \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
704 \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
705 \cfunction{PyGILState_Release}.
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
706
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
707 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
708 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
709 \versionadded{2.3}
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
710 \end{cfuncdesc}
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
711
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
712 \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
713 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
714 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
715 \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
716 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
717
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
718 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
719 \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
720 \versionadded{2.3}
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
721 \end{cfuncdesc}
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
722
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
723
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
724 \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
725
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
726 \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
727
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
728 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
729 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
730 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
731
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
732 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
733 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
734 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
735 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
736 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
737 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
738 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
739 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
740 previous versions.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
741
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
742 \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
743 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
744 PyObject *arg)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
745 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
746 \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
747 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
748 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
749 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
750 \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
751 \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
752 \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
753 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
754 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
755
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
756 \begin{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
757 \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
758 \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
759 \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
760 \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
761 \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
762 \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
763 \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
764 \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
765 \end{tableii}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
766 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
767
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
768 \begin{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
769 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
770 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
771 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
772 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
773 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
774 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
775
31796
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
776 \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
777 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
778 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
779 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
780 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
781 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
782 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
783 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
784 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
785 profiler.
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
786 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
787
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
788 \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
789 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
790 (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
791 reported.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
792 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
793
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
794 \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
795 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
796 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
797 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
798
31796
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
799 \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
800 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
801 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
802 \end{cvardesc}
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
803
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
804 \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
805 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
806 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
807 \end{cvardesc}
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
808
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
809 \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
810 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
811 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
812 \end{cvardesc}
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
813
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
814 \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
815 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
816 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
817 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
818 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
819 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
820 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
821 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
822
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
823 \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
824 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
825 \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
826 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
827 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
828
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
829
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
830 \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
831 \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
832
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
833 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
834 tools.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
835
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
836 \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
837 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
838 such objects.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
839 \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
840 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
841
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
842 \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
843 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
844 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
845 \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
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}{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
849 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
850 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
851 \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
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 \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
855 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
856 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
857 object.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
858 \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
859 \end{cfuncdesc}