Mercurial > cpython-lru_cache-weakref

annotate Doc/api/init.tex @ 34161:ca2ca1aeb080 2.4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Check in missing png version of pyfav.gif.
author Johannes Gijsbers <jlg@dds.nl>
date Mon, 13 Dec 2004 13:11:42 +0000
parents a46b76eb9053
children ad126054ade5
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
33189
de804edf8bcd Patch #900727: Add Py_InitializeEx to allow embedding without signals.
Martin v. Löwis <martin@v.loewis.de>
parents: 32575
diff changeset
26 \begin{cfuncdesc}{void}{Py_InitializeEx}{int initsigs}
33715
a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick
Tim Peters <tim.peters@gmail.com>
parents: 33189
diff changeset
27 This function works like \cfunction{Py_Initialize()} if
33189
de804edf8bcd Patch #900727: Add Py_InitializeEx to allow embedding without signals.
Martin v. Löwis <martin@v.loewis.de>
parents: 32575
diff changeset
28 \var{initsigs} is 1. If \var{initsigs} is 0, it skips
de804edf8bcd Patch #900727: Add Py_InitializeEx to allow embedding without signals.
Martin v. Löwis <martin@v.loewis.de>
parents: 32575
diff changeset
29 initialization registration of signal handlers, which
de804edf8bcd Patch #900727: Add Py_InitializeEx to allow embedding without signals.
Martin v. Löwis <martin@v.loewis.de>
parents: 32575
diff changeset
30 might be useful when Python is embedded. \versionadded{2.4}
de804edf8bcd Patch #900727: Add Py_InitializeEx to allow embedding without signals.
Martin v. Löwis <martin@v.loewis.de>
parents: 32575
diff changeset
31 \end{cfuncdesc}
de804edf8bcd Patch #900727: Add Py_InitializeEx to allow embedding without signals.
Martin v. Löwis <martin@v.loewis.de>
parents: 32575
diff changeset
32
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
33 \begin{cfuncdesc}{int}{Py_IsInitialized}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
34 Return true (nonzero) when the Python interpreter has been
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
35 initialized, false (zero) if not. After \cfunction{Py_Finalize()}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
36 is called, this returns false until \cfunction{Py_Initialize()} is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
37 called again.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
38 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
39
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
40 \begin{cfuncdesc}{void}{Py_Finalize}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
41 Undo all initializations made by \cfunction{Py_Initialize()} and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
42 subsequent use of Python/C API functions, and destroy all
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
43 sub-interpreters (see \cfunction{Py_NewInterpreter()} below) that
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
44 were created and not yet destroyed since the last call to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
45 \cfunction{Py_Initialize()}. Ideally, this frees all memory
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
46 allocated by the Python interpreter. This is a no-op when called
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
47 for a second time (without calling \cfunction{Py_Initialize()} again
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
48 first). There is no return value; errors during finalization are
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
49 ignored.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
50
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
51 This function is provided for a number of reasons. An embedding
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
52 application might want to restart Python without having to restart
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
53 the application itself. An application that has loaded the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
54 interpreter from a dynamically loadable library (or DLL) might want
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
55 to free all memory allocated by Python before unloading the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
56 DLL. During a hunt for memory leaks in an application a developer
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
57 might want to free all memory allocated by Python before exiting
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
58 from the application.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
59
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
60 \strong{Bugs and caveats:} The destruction of modules and objects in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
61 modules is done in random order; this may cause destructors
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
62 (\method{__del__()} methods) to fail when they depend on other
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
63 objects (even functions) or modules. Dynamically loaded extension
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
64 modules loaded by Python are not unloaded. Small amounts of memory
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
65 allocated by the Python interpreter may not be freed (if you find a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
66 leak, please report it). Memory tied up in circular references
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
67 between objects is not freed. Some memory allocated by extension
27798
e62099c65a3c A typo, and desist from inaccurately describing some things as lists.
Michael W. Hudson <mwh@python.net>
parents: 26558
diff changeset
68 modules may not be freed. Some extensions may not work properly if
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
69 their initialization routine is called more than once; this can
27798
e62099c65a3c A typo, and desist from inaccurately describing some things as lists.
Michael W. Hudson <mwh@python.net>
parents: 26558
diff changeset
70 happen if an application calls \cfunction{Py_Initialize()} and
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
71 \cfunction{Py_Finalize()} more than once.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
72 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
73
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
74 \begin{cfuncdesc}{PyThreadState*}{Py_NewInterpreter}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
75 Create a new sub-interpreter. This is an (almost) totally separate
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
76 environment for the execution of Python code. In particular, the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
77 new interpreter has separate, independent versions of all imported
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
78 modules, including the fundamental modules
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
79 \module{__builtin__}\refbimodindex{__builtin__},
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
80 \module{__main__}\refbimodindex{__main__} and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
81 \module{sys}\refbimodindex{sys}. The table of loaded modules
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
82 (\code{sys.modules}) and the module search path (\code{sys.path})
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
83 are also separate. The new environment has no \code{sys.argv}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
84 variable. It has new standard I/O stream file objects
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
85 \code{sys.stdin}, \code{sys.stdout} and \code{sys.stderr} (however
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
86 these refer to the same underlying \ctype{FILE} structures in the C
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
87 library).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
88 \withsubitem{(in module sys)}{
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
89 \ttindex{stdout}\ttindex{stderr}\ttindex{stdin}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
90
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
91 The return value points to the first thread state created in the new
31679
da78b96b6aab Minor grammatical fixes.
Brett Cannon <bcannon@gmail.com>
parents: 31678
diff changeset
92 sub-interpreter. This thread state is made in the current thread
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
93 state. Note that no actual thread is created; see the discussion of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
94 thread states below. If creation of the new interpreter is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
95 unsuccessful, \NULL{} is returned; no exception is set since the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
96 exception state is stored in the current thread state and there may
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
97 not be a current thread state. (Like all other Python/C API
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
98 functions, the global interpreter lock must be held before calling
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
99 this function and is still held when it returns; however, unlike
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
100 most other Python/C API functions, there needn't be a current thread
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
101 state on entry.)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
102
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
103 Extension modules are shared between (sub-)interpreters as follows:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
104 the first time a particular extension is imported, it is initialized
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
105 normally, and a (shallow) copy of its module's dictionary is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
106 squirreled away. When the same extension is imported by another
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
107 (sub-)interpreter, a new module is initialized and filled with the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
108 contents of this copy; the extension's \code{init} function is not
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
109 called. Note that this is different from what happens when an
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
110 extension is imported after the interpreter has been completely
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
111 re-initialized by calling
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
112 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
113 \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}; in that case,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
114 the extension's \code{init\var{module}} function \emph{is} called
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
115 again.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
116
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
117 \strong{Bugs and caveats:} Because sub-interpreters (and the main
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
118 interpreter) are part of the same process, the insulation between
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
119 them isn't perfect --- for example, using low-level file operations
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
120 like \withsubitem{(in module os)}{\ttindex{close()}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
121 \function{os.close()} they can (accidentally or maliciously) affect
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
122 each other's open files. Because of the way extensions are shared
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
123 between (sub-)interpreters, some extensions may not work properly;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
124 this is especially likely when the extension makes use of (static)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
125 global variables, or when the extension manipulates its module's
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
126 dictionary after its initialization. It is possible to insert
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
127 objects created in one sub-interpreter into a namespace of another
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
128 sub-interpreter; this should be done with great care to avoid
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
129 sharing user-defined functions, methods, instances or classes
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
130 between sub-interpreters, since import operations executed by such
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
131 objects may affect the wrong (sub-)interpreter's dictionary of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
132 loaded modules. (XXX This is a hard-to-fix bug that will be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
133 addressed in a future release.)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
134 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
135
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
136 \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
137 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
138 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
139 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
140 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
141 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
142 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
143 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
144 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
145 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
146 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
147
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
148 \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
149 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
150 \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
151 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
152 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
153 \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
154 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
155 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
156 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
157 \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
158 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
159 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
160 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
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_GetProgramName}{}
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 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
165 \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
166 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
167 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
168 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
169
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
170 \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
171 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
172 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
173 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
174 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
175 \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
176 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
177 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
178 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
179 \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
180 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
181 \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
182 function.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
183 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
184
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
185 \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
186 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
187 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
188 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
189 \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
190 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
191 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
192 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
193 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
194 \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
195 \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
196 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
197 \UNIX.
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 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
200 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
201 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
202 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
203 \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
204 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
205
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
206 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
207 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
208 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
209 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
210 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
211 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
212 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
213 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
214 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
215 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
216 (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
217 compiled!).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
218
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
219 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
220 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
221 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
222 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
223 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
224
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
225 \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
226 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
227 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
228 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
229 \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
230 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
231 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
232 \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
233 \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
234 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
235
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
236 \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
237 \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
238 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
239 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
240 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
241 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
242 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
243 \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
244 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
245 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
246 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
247 \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
248 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
249 modules.
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 % 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
252 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
253
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
254 \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
255 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
256 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
257
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
258 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
259 "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
260 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
261
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
262 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
263 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
264 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
265 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
266 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
267 \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
268 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
269
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
270 \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
271 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
272 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
273 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
274 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
275 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
276 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
277 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
278 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
279 \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
280 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
281
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
282 \begin{cfuncdesc}{const char*}{Py_GetCopyright}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
283 Return the 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
284 for example
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
285
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
286 \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
287
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
288 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
289 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
290 \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
291 \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
292 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
293
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
294 \begin{cfuncdesc}{const char*}{Py_GetCompiler}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
295 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
296 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
297
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
298 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
299 "[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
300 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
301
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
302 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
303 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
304 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
305 \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
306 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
307
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
308 \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
309 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
310 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
311
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
312 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
313 "#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
314 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
315
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
316 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
317 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
318 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
319 \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
320 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
321
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
322 \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
323 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
324 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
325 \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
326 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
327 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
328 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
329 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
330 \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
331 \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
332 \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
333 % 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
334 % 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
335 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
336
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
337 % 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
338
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
339 \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
340 \label{threads}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
341
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
342 \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
343 \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
344 \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
345
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
346 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
347 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
348 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
349 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
350 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
351 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
352 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
353
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
354 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
355 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
356 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
357 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
358 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
359 \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
360 \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
361 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
362 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
363 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
364
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
365 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
366 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
367 \ctype{PyThreadState}\ttindex{PyThreadState}. There's one global
511ffc62b298 Remove a few elderly sentences
Andrew M. Kuchling <amk@amk.ca>
parents: 32574
diff changeset
368 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
369 \ctype{PyThreadState}\ttindex{PyThreadState} structure. While most
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
370 thread packages have a way to store ``per-thread global data,''
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
371 Python's internal platform independent thread abstraction doesn't
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
372 support this yet. Therefore, the current thread state must be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
373 manipulated explicitly.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
374
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
375 This is easy enough in most cases. Most code manipulating the global
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
376 interpreter lock has the following simple structure:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
377
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
378 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
379 Save the thread state in a local variable.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
380 Release the interpreter lock.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
381 ...Do some blocking I/O operation...
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
382 Reacquire the interpreter lock.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
383 Restore the thread state from the local variable.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
384 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
385
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
386 This is so common that a pair of macros exists to simplify it:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
387
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
388 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
389 Py_BEGIN_ALLOW_THREADS
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
390 ...Do some blocking I/O operation...
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
391 Py_END_ALLOW_THREADS
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
392 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
393
22923
a5eeb288e020 Update to use the new \csimplemacro macro
Fred Drake <fdrake@acm.org>
parents: 20460
diff changeset
394 The
a5eeb288e020 Update to use the new \csimplemacro macro
Fred Drake <fdrake@acm.org>
parents: 20460
diff changeset
395 \csimplemacro{Py_BEGIN_ALLOW_THREADS}\ttindex{Py_BEGIN_ALLOW_THREADS}
a5eeb288e020 Update to use the new \csimplemacro macro
Fred Drake <fdrake@acm.org>
parents: 20460
diff changeset
396 macro opens a new block and declares a hidden local variable; the
a5eeb288e020 Update to use the new \csimplemacro macro
Fred Drake <fdrake@acm.org>
parents: 20460
diff changeset
397 \csimplemacro{Py_END_ALLOW_THREADS}\ttindex{Py_END_ALLOW_THREADS}
a5eeb288e020 Update to use the new \csimplemacro macro
Fred Drake <fdrake@acm.org>
parents: 20460
diff changeset
398 macro closes the block. Another advantage of using these two macros
a5eeb288e020 Update to use the new \csimplemacro macro
Fred Drake <fdrake@acm.org>
parents: 20460
diff changeset
399 is that when Python is compiled without thread support, they are
a5eeb288e020 Update to use the new \csimplemacro macro
Fred Drake <fdrake@acm.org>
parents: 20460
diff changeset
400 defined empty, thus saving the thread state and lock manipulations.
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
401
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
402 When thread support is enabled, the block above expands to the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
403 following code:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
404
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
405 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
406 PyThreadState *_save;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
407
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
408 _save = PyEval_SaveThread();
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
409 ...Do some blocking I/O operation...
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
410 PyEval_RestoreThread(_save);
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
411 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
412
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
413 Using even lower level primitives, we can get roughly the same effect
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
414 as follows:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
415
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
416 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
417 PyThreadState *_save;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
418
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
419 _save = PyThreadState_Swap(NULL);
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
420 PyEval_ReleaseLock();
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
421 ...Do some blocking I/O operation...
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
422 PyEval_AcquireLock();
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
423 PyThreadState_Swap(_save);
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
424 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
425
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
426 There are some subtle differences; in particular,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
427 \cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()} saves
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
428 and restores the value of the global variable
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
429 \cdata{errno}\ttindex{errno}, since the lock manipulation does not
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
430 guarantee that \cdata{errno} is left alone. Also, when thread support
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
431 is disabled,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
432 \cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
433 \cfunction{PyEval_RestoreThread()} don't manipulate the lock; in this
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
434 case, \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
435 \cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()} are not
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
436 available. This is done so that dynamically loaded extensions
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
437 compiled with thread support enabled can be loaded by an interpreter
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
438 that was compiled with disabled thread support.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
439
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
440 The global interpreter lock is used to protect the pointer to the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
441 current thread state. When releasing the lock and saving the thread
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
442 state, the current thread state pointer must be retrieved before the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
443 lock is released (since another thread could immediately acquire the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
444 lock and store its own thread state in the global variable).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
445 Conversely, when acquiring the lock and restoring the thread state,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
446 the lock must be acquired before storing the thread state pointer.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
447
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
448 Why am I going on with so much detail about this? Because when
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
449 threads are created from C, they don't have the global interpreter
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
450 lock, nor is there a thread state data structure for them. Such
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
451 threads must bootstrap themselves into existence, by first creating a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
452 thread state data structure, then acquiring the lock, and finally
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
453 storing their thread state pointer, before they can start using the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
454 Python/C API. When they are done, they should reset the thread state
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
455 pointer, release the lock, and finally free their thread state data
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
456 structure.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
457
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
458 When creating a thread data structure, you need to provide an
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
459 interpreter state data structure. The interpreter state data
31679
da78b96b6aab Minor grammatical fixes.
Brett Cannon <bcannon@gmail.com>
parents: 31678
diff changeset
460 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
461 interpreter, for example the module administration
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
462 (\code{sys.modules}). Depending on your needs, you can either create
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
463 a new interpreter state data structure, or share the interpreter state
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
464 data structure used by the Python main thread (to access the latter,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
465 you must obtain the thread state and access its \member{interp} member;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
466 this must be done by a thread that is created by Python or by the main
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
467 thread after Python is initialized).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
468
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
469 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
470 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
471
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 \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
473 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
474 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
475
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
476 /* 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
477 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
478 /* 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
479
9ca4a67b9973 Commit MvL's doc patch for SF bug #221327. This adds an example of
Guido van Rossum <guido@python.org>
parents: 27798
diff changeset
480 /* 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
481 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
482 \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
483
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
484 \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
485 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
486 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
487 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
488 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
489
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
490 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
491 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
492 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
493 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
494 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
495
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
496 \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
497 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
498 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
499 *}\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
500 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
501
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
502 \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
503 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
504 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
505 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
506 \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
507 \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
508 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
509 \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
510 \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
511
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
512 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
513 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
514 \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
515
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
516 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
517 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
518 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
519 Therefore, the lock is not created initially. This situation is
33715
a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick
Tim Peters <tim.peters@gmail.com>
parents: 33189
diff changeset
520 equivalent to having acquired the lock: when there is only a single
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
521 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
522 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
523 \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
524 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
525 yet, it calls \cfunction{PyEval_InitThreads()}. When this call
33715
a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick
Tim Peters <tim.peters@gmail.com>
parents: 33189
diff changeset
526 returns, it is guaranteed that the lock has been created and that the
a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick
Tim Peters <tim.peters@gmail.com>
parents: 33189
diff changeset
527 calling thread has acquired it.
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
528
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
529 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
530 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
531
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
532 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
533 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
33715
a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick
Tim Peters <tim.peters@gmail.com>
parents: 33189
diff changeset
536 \begin{cfuncdesc}{int}{PyEval_ThreadsInitialized}{}
a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick
Tim Peters <tim.peters@gmail.com>
parents: 33189
diff changeset
537 Returns a non-zero value if \cfunction{PyEval_InitThreads()} has been
a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick
Tim Peters <tim.peters@gmail.com>
parents: 33189
diff changeset
538 called. This function can be called without holding the lock, and
a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick
Tim Peters <tim.peters@gmail.com>
parents: 33189
diff changeset
539 therefore can be used to avoid calls to the locking API when running
a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick
Tim Peters <tim.peters@gmail.com>
parents: 33189
diff changeset
540 single-threaded. This function is not available when thread support
a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick
Tim Peters <tim.peters@gmail.com>
parents: 33189
diff changeset
541 is disabled at compile time. \versionadded{2.4}
a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick
Tim Peters <tim.peters@gmail.com>
parents: 33189
diff changeset
542 \end{cfuncdesc}
a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick
Tim Peters <tim.peters@gmail.com>
parents: 33189
diff changeset
543
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
544 \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
545 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
546 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
547 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
548 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
549 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
550
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
551 \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
552 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
553 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
554 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
555 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
556
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
557 \begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate}
31679
da78b96b6aab Minor grammatical fixes.
Brett Cannon <bcannon@gmail.com>
parents: 31678
diff changeset
558 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
559 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
560 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
561 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
562 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
563 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
564
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
565 \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
566 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
567 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
568 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
569 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
570 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
571 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
572 compile time.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
573 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
574
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
575 \begin{cfuncdesc}{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
576 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
577 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
578 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
579 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
580 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
581 compile time.)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
582 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
583
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
584 \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
585 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
586 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
587 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
588 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
589 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
590 compile time.)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
591 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
592
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
593 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
594 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
595
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
596 \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
597 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
598 \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
599 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
600 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
601 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
602 is disabled at compile time.
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
603 \end{csimplemacrodesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
604
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
605 \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
606 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
607 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
608 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
609 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
610 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
611 \end{csimplemacrodesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
612
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
613 \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
614 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
615 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
616 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
617 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
618 \end{csimplemacrodesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
619
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
620 \begin{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
621 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
622 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
623 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
624 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
625 \end{csimplemacrodesc}
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 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
628 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
629 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
630
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
631 \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
632 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
633 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
634 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
635 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
636
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
637 \begin{cfuncdesc}{void}{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
638 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
639 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
640 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
641
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
642 \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
643 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
644 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
645 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
646 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
647
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
648 \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
649 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
650 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
651 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
652 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
653
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
654 \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
655 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
656 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
657 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
658
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
659 \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
660 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
661 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
662 \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
663 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
664
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
665 \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
666 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
667 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
668 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
669 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
670
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
671 \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
672 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
673 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
674 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
675 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
676
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
677 \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
678 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
679 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
680 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
681 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
682 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
683 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
684 \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
685 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
686 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
687
29649
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
688 \begin{cfuncdesc}{int}{PyThreadState_SetAsyncExc}{long id, PyObject *exc}
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
689 Asynchronously raise an exception in a thread.
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
690 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
691 \var{exc} is the exception object to be raised.
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
692 This function does not steal any references to \var{exc}.
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
693 To prevent naive misuse, you must write your own C extension
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
694 to call this. Must be called with the GIL held.
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
695 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
696 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
697 with \var{exc} set to \constant{NULL} to revert the effect.
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
698 This raises no exceptions.
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
699 \versionadded{2.3}
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
700 \end{cfuncdesc}
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
701
32573
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
702 \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
703 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
704 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
705 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
706 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
707 \cfunction{PyGILState_Release()}.
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
708 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
709 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
710 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
711 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
712 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
713
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
714 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
715 \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
716 \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
717 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
718 \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
719 \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
720 \cfunction{PyGILState_Release}.
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
721
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
722 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
723 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
724 \versionadded{2.3}
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
725 \end{cfuncdesc}
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
726
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
727 \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
728 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
729 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
730 \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
731 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
732
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
733 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
734 \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
735 \versionadded{2.3}
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
736 \end{cfuncdesc}
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
737
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
738
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
739 \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
740
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
741 \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
742
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
743 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
744 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
745 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
746
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
747 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
748 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
749 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
750 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
751 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
752 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
753 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
754 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
755 previous versions.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
756
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
757 \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
758 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
759 PyObject *arg)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
760 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
761 \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
762 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
763 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
764 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
765 \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
766 \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
767 \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
768 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
769 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
770
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
771 \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
772 \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
773 \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
774 \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
775 \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
776 \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
777 \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
778 \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
779 \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
780 \end{tableii}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
781 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
782
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
783 \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
784 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
785 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
786 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
787 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
788 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
789 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
790
31796
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
791 \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
792 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
793 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
794 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
795 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
796 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
797 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
798 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
799 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
800 profiler.
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
801 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
802
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
803 \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
804 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
805 (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
806 reported.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
807 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
808
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
809 \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
810 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
811 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
812 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
813
31796
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
814 \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
815 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
816 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
817 \end{cvardesc}
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
818
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
819 \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
820 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
821 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
822 \end{cvardesc}
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
823
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
824 \begin{cvardesc}{int}{PyTrace_C_RETURN}
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
825 The value for the \var{what} parameter to \ctype{Py_tracefunc}
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
826 functions when a C function has returned.
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
827 \end{cvardesc}
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
828
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
829 \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
830 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
831 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
832 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
833 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
834 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
835 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
836 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
837
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
838 \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
839 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
840 \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
841 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
842 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
843
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
844
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
845 \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
846 \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
847
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
848 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
849 tools.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
850
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
851 \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
852 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
853 such objects.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
854 \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
855 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
856
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
857 \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
858 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
859 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
860 \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
861 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
862
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
863 \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
864 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
865 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
866 \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
867 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
868
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
869 \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
870 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
871 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
872 object.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
873 \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
874 \end{cfuncdesc}