Mercurial > cpython-lru_cache-weakref

annotate Doc/api/init.tex @ 38664:7619216bbc19 2.4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Bug #1502728: Correctly link against librt library on HP-UX. (backport from rev. 46743)
author Georg Brandl <georg@python.org>
date Thu, 08 Jun 2006 12:54:16 +0000
parents 7e7e86f45255
children 585059de2b40
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
34586
7e7e86f45255 Update refences to "Macintosh" to reflect the state of affairs for OS X and not
Brett Cannon <bcannon@gmail.com>
parents: 34452
diff changeset
242 character. The delimiter character is \character{:} on \UNIX and Mac OS X,
7e7e86f45255 Update refences to "Macintosh" to reflect the state of affairs for OS X and not
Brett Cannon <bcannon@gmail.com>
parents: 34452
diff changeset
243 \character{;} on Windows. The returned string points into
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
244 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
245 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
246 \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
247 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
248 modules.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
249
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
250 % 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
251 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
252
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
253 \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
254 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
255 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
256
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
257 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
258 "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
259 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
260
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
261 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
262 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
263 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
264 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
265 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
266 \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
267 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
268
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
269 \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
270 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
271 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
272 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
273 e.g., for Solaris 2.x, which is also known as SunOS 5.x, the value
34586
7e7e86f45255 Update refences to "Macintosh" to reflect the state of affairs for OS X and not
Brett Cannon <bcannon@gmail.com>
parents: 34452
diff changeset
274 is \code{'sunos5'}. On Mac OS X, it is \code{'darwin'}. On Windows,
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
275 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
276 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
277 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
278 \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
279 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
280
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
281 \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
282 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
283 for example
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
284
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
285 \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
286
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
287 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
288 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
289 \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
290 \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
291 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
292
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
293 \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
294 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
295 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
296
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
297 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
298 "[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
299 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
300
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
301 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
302 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
303 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
304 \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
305 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
306
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
307 \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
308 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
309 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
310
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
311 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
312 "#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
313 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
314
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
315 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
316 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
317 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
318 \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
319 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
320
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
321 \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
322 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
323 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
324 \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
325 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
326 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
327 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
328 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
329 \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
330 \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
331 \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
332 % 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
333 % 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
334 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
335
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
336 % 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
337
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
338 \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
339 \label{threads}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
340
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
341 \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
342 \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
343 \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
344
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
345 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
346 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
347 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
348 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
349 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
350 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
351 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
352
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
353 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
354 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
355 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
356 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
357 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
358 \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
359 \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
360 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
361 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
362 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
363
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
364 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
365 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
366 \ctype{PyThreadState}\ttindex{PyThreadState}. There's one global
511ffc62b298 Remove a few elderly sentences
Andrew M. Kuchling <amk@amk.ca>
parents: 32574
diff changeset
367 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
368 \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
369 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
370 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
371 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
372 manipulated explicitly.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
373
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
374 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
375 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
376
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
377 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
378 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
379 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
380 ...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
381 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
382 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
383 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
384
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
385 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
386
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
387 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
388 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
389 ...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
390 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
391 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
392
22923
a5eeb288e020 Update to use the new \csimplemacro macro
Fred Drake <fdrake@acm.org>
parents: 20460
diff changeset
393 The
a5eeb288e020 Update to use the new \csimplemacro macro
Fred Drake <fdrake@acm.org>
parents: 20460
diff changeset
394 \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
395 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
396 \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
397 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
398 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
399 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
400
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
401 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
402 following code:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
403
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
404 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
405 PyThreadState *_save;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
406
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
407 _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
408 ...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
409 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
410 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
411
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
412 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
413 as follows:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
414
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
415 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
416 PyThreadState *_save;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
417
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
418 _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
419 PyEval_ReleaseLock();
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
420 ...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
421 PyEval_AcquireLock();
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
422 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
423 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
424
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
425 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
426 \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
427 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
428 \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
429 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
430 is disabled,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
431 \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
432 \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
433 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
434 \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
435 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
436 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
437 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
438
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
439 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
440 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
441 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
442 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
443 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
444 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
445 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
446
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
447 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
448 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
449 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
450 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
451 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
452 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
453 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
454 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
455 structure.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
456
34452
ad126054ade5 Clean up discussion of new C thread idiom
Fred Drake <fdrake@acm.org>
parents: 33715
diff changeset
457 Beginning with version 2.3, threads can now take advantage of the
ad126054ade5 Clean up discussion of new C thread idiom
Fred Drake <fdrake@acm.org>
parents: 33715
diff changeset
458 \cfunction{PyGILState_*()} functions to do all of the above
ad126054ade5 Clean up discussion of new C thread idiom
Fred Drake <fdrake@acm.org>
parents: 33715
diff changeset
459 automatically. The typical idiom for calling into Python from a C
ad126054ade5 Clean up discussion of new C thread idiom
Fred Drake <fdrake@acm.org>
parents: 33715
diff changeset
460 thread is now:
28133
9ca4a67b9973 Commit MvL's doc patch for SF bug #221327. This adds an example of
Guido van Rossum <guido@python.org>
parents: 27798
diff changeset
461
9ca4a67b9973 Commit MvL's doc patch for SF bug #221327. This adds an example of
Guido van Rossum <guido@python.org>
parents: 27798
diff changeset
462 \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
463 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
464 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
465
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
466 /* 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
467 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
468 /* 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
469
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 /* 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
471 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
472 \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
473
34452
ad126054ade5 Clean up discussion of new C thread idiom
Fred Drake <fdrake@acm.org>
parents: 33715
diff changeset
474 Note that the \cfunction{PyGILState_*()} functions assume there is only
ad126054ade5 Clean up discussion of new C thread idiom
Fred Drake <fdrake@acm.org>
parents: 33715
diff changeset
475 one global interpreter (created automatically by
ad126054ade5 Clean up discussion of new C thread idiom
Fred Drake <fdrake@acm.org>
parents: 33715
diff changeset
476 \cfunction{Py_Initialize()}). Python still supports the creation of
ad126054ade5 Clean up discussion of new C thread idiom
Fred Drake <fdrake@acm.org>
parents: 33715
diff changeset
477 additional interpreters (using \cfunction{Py_NewInterpreter()}), but
ad126054ade5 Clean up discussion of new C thread idiom
Fred Drake <fdrake@acm.org>
parents: 33715
diff changeset
478 mixing multiple interpreters and the \cfunction{PyGILState_*()} API is
ad126054ade5 Clean up discussion of new C thread idiom
Fred Drake <fdrake@acm.org>
parents: 33715
diff changeset
479 unsupported.
ad126054ade5 Clean up discussion of new C thread idiom
Fred Drake <fdrake@acm.org>
parents: 33715
diff changeset
480
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
481 \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
482 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
483 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
484 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
485 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
486
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
487 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
488 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
489 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
490 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
491 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
492
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
493 \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
494 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
495 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
496 *}\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
497 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
498
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
499 \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
500 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
501 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
502 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
503 \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
504 \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
505 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
506 \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
507 \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
508
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
509 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
510 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
511 \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
512
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
513 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
514 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
515 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
516 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
517 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
518 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
519 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
520 \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
521 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
522 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
523 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
524 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
525
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
526 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
527 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
528
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
529 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
530 compile time.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
531 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
532
33715
a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick
Tim Peters <tim.peters@gmail.com>
parents: 33189
diff changeset
533 \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
534 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
535 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
536 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
537 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
538 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
539 \end{cfuncdesc}
a46b76eb9053 SF patch 1044089: New C API function PyEval_ThreadsInitialized(), by Nick
Tim Peters <tim.peters@gmail.com>
parents: 33189
diff changeset
540
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
541 \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
542 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
543 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
544 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
545 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
546 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
547
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
548 \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
549 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
550 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
551 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
552 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
553
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
554 \begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate}
31679
da78b96b6aab Minor grammatical fixes.
Brett Cannon <bcannon@gmail.com>
parents: 31678
diff changeset
555 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
556 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
557 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
558 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
559 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
560 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
561
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
562 \begin{cfuncdesc}{void}{PyEval_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
563 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
564 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
565 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
566 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
567 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
568 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
569 compile time.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
570 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
571
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
572 \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
573 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
574 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
575 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
576 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
577 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
578 compile time.)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
579 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
580
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
581 \begin{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
582 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
583 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
584 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
585 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
586 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
587 compile time.)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
588 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
589
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
590 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
591 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
592
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
593 \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
594 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
595 \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
596 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
597 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
598 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
599 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
600 \end{csimplemacrodesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
601
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
602 \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
603 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
604 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
605 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
606 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
607 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
608 \end{csimplemacrodesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
609
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
610 \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
611 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
612 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
613 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
614 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
615 \end{csimplemacrodesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
616
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
617 \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
618 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
619 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
620 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
621 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
622 \end{csimplemacrodesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
623
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
624 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
625 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
626 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
627
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
628 \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
629 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
630 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
631 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
632 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
633
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
634 \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
635 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
636 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
637 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
638
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
639 \begin{cfuncdesc}{void}{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
640 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
641 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
642 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
643 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
644
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
645 \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
646 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
647 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
648 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
649 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
650
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
651 \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
652 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
653 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
654 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
655
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
656 \begin{cfuncdesc}{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
657 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
658 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
659 \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
660 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
661
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
662 \begin{cfuncdesc}{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
663 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
664 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
665 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
666 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
667
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
668 \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
669 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
670 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
671 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
672 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
673
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
674 \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
675 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
676 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
677 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
678 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
679 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
680 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
681 \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
682 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
683 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
684
29649
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
685 \begin{cfuncdesc}{int}{PyThreadState_SetAsyncExc}{long id, PyObject *exc}
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
686 Asynchronously raise an exception in a thread.
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
687 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
688 \var{exc} is the exception object to be raised.
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
689 This function does not steal any references to \var{exc}.
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
690 To prevent naive misuse, you must write your own C extension
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
691 to call this. Must be called with the GIL held.
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
692 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
693 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
694 with \var{exc} set to \constant{NULL} to revert the effect.
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
695 This raises no exceptions.
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
696 \versionadded{2.3}
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
697 \end{cfuncdesc}
8bd2580e0155 Document PyThreadState_SetAsyncExc().
Fred Drake <fdrake@acm.org>
parents: 28616
diff changeset
698
32573
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
699 \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
700 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
701 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
702 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
703 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
704 \cfunction{PyGILState_Release()}.
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
705 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
706 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
707 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
708 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
709 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
710
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
711 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
712 \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
713 \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
714 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
715 \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
716 \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
717 \cfunction{PyGILState_Release}.
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
718
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
719 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
720 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
721 \versionadded{2.3}
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
722 \end{cfuncdesc}
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
723
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
724 \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
725 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
726 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
727 \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
728 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
729
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
730 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
731 \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
732 \versionadded{2.3}
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
733 \end{cfuncdesc}
153c517bc6e9 [Bug #987835] Add documentation from PEP 311. (Untested TeX code.)
Andrew M. Kuchling <amk@amk.ca>
parents: 31796
diff changeset
734
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
735
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
736 \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
737
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
738 \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
739
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
740 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
741 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
742 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
743
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
744 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
745 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
746 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
747 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
748 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
749 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
750 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
751 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
752 previous versions.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
753
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
754 \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
755 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
756 PyObject *arg)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
757 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
758 \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
759 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
760 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
761 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
762 \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
763 \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
764 \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
765 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
766 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
767
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
768 \begin{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
769 \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
770 \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
771 \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
772 \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
773 \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
774 \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
775 \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
776 \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
777 \end{tableii}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
778 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
779
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
780 \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
781 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
782 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
783 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
784 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
785 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
786 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
787
31796
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
788 \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
789 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
790 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
791 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
792 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
793 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
794 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
795 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
796 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
797 profiler.
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
798 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
799
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
800 \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
801 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
802 (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
803 reported.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
804 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
805
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
806 \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
807 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
808 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
809 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
810
31796
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
811 \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
812 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
813 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
814 \end{cvardesc}
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
815
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
816 \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
817 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
818 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
819 \end{cvardesc}
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
820
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
821 \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
822 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
823 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
824 \end{cvardesc}
1c117dbb2def Enable the profiling of C functions (builtins and extensions)
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31679
diff changeset
825
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
826 \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
827 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
828 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
829 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
830 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
831 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
832 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
833 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
834
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
835 \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
836 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
837 \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
838 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
839 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
840
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
841
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
842 \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
843 \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
844
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
845 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
846 tools.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
847
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
848 \begin{cfuncdesc}{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
849 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
850 such objects.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
851 \versionadded{2.2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
852 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
853
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
854 \begin{cfuncdesc}{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
855 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
856 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
857 \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
858 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
859
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
860 \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
861 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
862 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
863 \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
864 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
865
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
866 \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
867 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
868 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
869 object.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
870 \versionadded{2.2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
871 \end{cfuncdesc}