cpython-lru_cache-weakref: Doc/c-api/init.rst annotate

annotate Doc/c-api/init.rst @ 78069:a8aa77458e12 3.2

Add c_size_t and c_ssize_t to the ctypes summary table.

author	Antoine Pitrou <solipsis@pitrou.net>
date	Thu, 12 Jul 2012 20:31:50 +0200
parents	69527695eff8
children	90f0dd118aa4

rev	line source
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1 .. highlightlang:: c
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4 .. _initialization:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6 *****************************************
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7 Initialization, Finalization, and Threads
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 *****************************************
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	11 Initializing and finalizing the interpreter
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	12 ===========================================
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	13
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	14
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	15 .. c:function:: void Py_Initialize()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 single: Py_SetProgramName()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19 single: PyEval_InitThreads()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20 single: modules (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 single: path (in module sys)
44098 0889daf6d0d9 #1535: rename __builtin__ module to builtins. Georg Brandl <georg@python.org> parents: 43174 diff changeset	22 module: builtins
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23 module: __main__
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 module: sys
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 triple: module; search; path
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26 single: PySys_SetArgv()
61791 9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	27 single: PySys_SetArgvEx()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 single: Py_Finalize()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30 Initialize the Python interpreter. In an application embedding Python, this
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31 should be called before using any other Python/C API functions; with the
74295 69527695eff8 Py_SetPythonHome() can be called before Py_Initialize(); thanks to Cody Smith from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 72176 diff changeset	32 exception of :c:func:`Py_SetProgramName`, :c:func:`Py_SetPythonHome` and :c:func:`Py_SetPath`. This initializes
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	33 the table of loaded modules (``sys.modules``), and creates the fundamental
44098 0889daf6d0d9 #1535: rename __builtin__ module to builtins. Georg Brandl <georg@python.org> parents: 43174 diff changeset	34 modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`. It also initializes
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35 the module search path (``sys.path``). It does not set ``sys.argv``; use
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	36 :c:func:`PySys_SetArgvEx` for that. This is a no-op when called for a second time
521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	37 (without calling :c:func:`Py_Finalize` first). There is no return value; it is a
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38 fatal error if the initialization fails.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	41 .. c:function:: void Py_InitializeEx(int initsigs)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	43 This function works like :c:func:`Py_Initialize` if initsigs is 1. If
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44 initsigs is 0, it skips initialization registration of signal handlers, which
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45 might be useful when Python is embedded.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	48 .. c:function:: int Py_IsInitialized()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50 Return true (nonzero) when the Python interpreter has been initialized, false
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	51 (zero) if not. After :c:func:`Py_Finalize` is called, this returns false until
521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	52 :c:func:`Py_Initialize` is called again.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	55 .. c:function:: void Py_Finalize()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	57 Undo all initializations made by :c:func:`Py_Initialize` and subsequent use of
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58 Python/C API functions, and destroy all sub-interpreters (see
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	59 :c:func:`Py_NewInterpreter` below) that were created and not yet destroyed since
521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	60 the last call to :c:func:`Py_Initialize`. Ideally, this frees all memory
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61 allocated by the Python interpreter. This is a no-op when called for a second
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	62 time (without calling :c:func:`Py_Initialize` again first). There is no return
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63 value; errors during finalization are ignored.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65 This function is provided for a number of reasons. An embedding application
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 might want to restart Python without having to restart the application itself.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67 An application that has loaded the Python interpreter from a dynamically
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68 loadable library (or DLL) might want to free all memory allocated by Python
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69 before unloading the DLL. During a hunt for memory leaks in an application a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 developer might want to free all memory allocated by Python before exiting from
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71 the application.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73 Bugs and caveats: The destruction of modules and objects in modules is done
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74 in random order; this may cause destructors (:meth:`__del__` methods) to fail
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75 when they depend on other objects (even functions) or modules. Dynamically
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76 loaded extension modules loaded by Python are not unloaded. Small amounts of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77 memory allocated by the Python interpreter may not be freed (if you find a leak,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78 please report it). Memory tied up in circular references between objects is not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79 freed. Some memory allocated by extension modules may not be freed. Some
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80 extensions may not work properly if their initialization routine is called more
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	81 than once; this can happen if an application calls :c:func:`Py_Initialize` and
521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	82 :c:func:`Py_Finalize` more than once.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	85 Process-wide parameters
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	86 =======================
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	89 .. c:function:: void Py_SetProgramName(wchar_t *name)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92 single: Py_Initialize()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93 single: main()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94 single: Py_GetPath()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	96 This function should be called before :c:func:`Py_Initialize` is called for
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97 the first time, if it is called at all. It tells the interpreter the value
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	98 of the ``argv[0]`` argument to the :c:func:`main` function of the program
46318 22a74eaf6b22 Change command line processing API to use wchar_t. Martin v. Löwis <martin@v.loewis.de> parents: 44396 diff changeset	99 (converted to wide characters).
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	100 This is used by :c:func:`Py_GetPath` and some other functions below to find
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101 the Python run-time libraries relative to the interpreter executable. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 default value is ``'python'``. The argument should point to a
46318 22a74eaf6b22 Change command line processing API to use wchar_t. Martin v. Löwis <martin@v.loewis.de> parents: 44396 diff changeset	103 zero-terminated wide character string in static storage whose contents will not
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104 change for the duration of the program's execution. No code in the Python
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105 interpreter will change the contents of this storage.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	108 .. c:function:: wchar* Py_GetProgramName()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110 .. index:: single: Py_SetProgramName()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	112 Return the program name set with :c:func:`Py_SetProgramName`, or the default.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113 The returned string points into static storage; the caller should not modify its
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114 value.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	117 .. c:function:: wchar_t* Py_GetPrefix()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119 Return the prefix for installed platform-independent files. This is derived
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120 through a number of complicated rules from the program name set with
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	121 :c:func:`Py_SetProgramName` and some environment variables; for example, if the
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122 program name is ``'/usr/local/bin/python'``, the prefix is ``'/usr/local'``. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123 returned string points into static storage; the caller should not modify its
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124 value. This corresponds to the :makevar:`prefix` variable in the top-level
72176 67a57c50a3e9 Fix some misuses of Sphinx roles and one typo Éric Araujo <merwok@netwok.org> parents: 71769 diff changeset	125 :file:`Makefile` and the ``--prefix`` argument to the :program:`configure`
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126 script at build time. The value is available to Python code as ``sys.prefix``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127 It is only useful on Unix. See also the next function.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	130 .. c:function:: wchar_t* Py_GetExecPrefix()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132 Return the exec-prefix for installed platform-dependent files. This is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133 derived through a number of complicated rules from the program name set with
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	134 :c:func:`Py_SetProgramName` and some environment variables; for example, if the
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135 program name is ``'/usr/local/bin/python'``, the exec-prefix is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136 ``'/usr/local'``. The returned string points into static storage; the caller
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137 should not modify its value. This corresponds to the :makevar:`exec_prefix`
72176 67a57c50a3e9 Fix some misuses of Sphinx roles and one typo Éric Araujo <merwok@netwok.org> parents: 71769 diff changeset	138 variable in the top-level :file:`Makefile` and the ``--exec-prefix``
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139 argument to the :program:`configure` script at build time. The value is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140 available to Python code as ``sys.exec_prefix``. It is only useful on Unix.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142 Background: The exec-prefix differs from the prefix when platform dependent
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	143 files (such as executables and shared libraries) are installed in a different
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144 directory tree. In a typical installation, platform dependent files may be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145 installed in the :file:`/usr/local/plat` subtree while platform independent may
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146 be installed in :file:`/usr/local`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	147
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	148 Generally speaking, a platform is a combination of hardware and software
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149 families, e.g. Sparc machines running the Solaris 2.x operating system are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150 considered the same platform, but Intel machines running Solaris 2.x are another
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151 platform, and Intel machines running Linux are yet another platform. Different
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 major revisions of the same operating system generally also form different
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153 platforms. Non-Unix operating systems are a different story; the installation
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154 strategies on those systems are so different that the prefix and exec-prefix are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155 meaningless, and set to the empty string. Note that compiled Python bytecode
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	156 files are platform independent (but not independent from the Python version by
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	157 which they were compiled!).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	159 System administrators will know how to configure the :program:`mount` or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160 :program:`automount` programs to share :file:`/usr/local` between platforms
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161 while having :file:`/usr/local/plat` be a different filesystem for each
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162 platform.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	165 .. c:function:: wchar_t* Py_GetProgramFullPath()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	166
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168 single: Py_SetProgramName()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	169 single: executable (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	170
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171 Return the full program name of the Python executable; this is computed as a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	172 side-effect of deriving the default module search path from the program name
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	173 (set by :c:func:`Py_SetProgramName` above). The returned string points into
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	174 static storage; the caller should not modify its value. The value is available
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	175 to Python code as ``sys.executable``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	176
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	177
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	178 .. c:function:: wchar_t* Py_GetPath()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	179
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	180 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	181 triple: module; search; path
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182 single: path (in module sys)
64955 fd5e51035335 issue 9910 Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 63674 diff changeset	183 single: Py_SetPath()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184
58219 aadfc31b3f14 Merged revisions 77389 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 57798 diff changeset	185 Return the default module search path; this is computed from the program name
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	186 (set by :c:func:`Py_SetProgramName` above) and some environment variables.
58219 aadfc31b3f14 Merged revisions 77389 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 57798 diff changeset	187 The returned string consists of a series of directory names separated by a
aadfc31b3f14 Merged revisions 77389 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 57798 diff changeset	188 platform dependent delimiter character. The delimiter character is ``':'``
aadfc31b3f14 Merged revisions 77389 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 57798 diff changeset	189 on Unix and Mac OS X, ``';'`` on Windows. The returned string points into
aadfc31b3f14 Merged revisions 77389 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 57798 diff changeset	190 static storage; the caller should not modify its value. The list
aadfc31b3f14 Merged revisions 77389 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 57798 diff changeset	191 :data:`sys.path` is initialized with this value on interpreter startup; it
aadfc31b3f14 Merged revisions 77389 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 57798 diff changeset	192 can be (and usually is) modified later to change the search path for loading
aadfc31b3f14 Merged revisions 77389 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 57798 diff changeset	193 modules.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	194
44396 6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44129 diff changeset	195 .. XXX should give the exact rules
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	196
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	198 .. c:function:: void Py_SetPath(const wchar_t *)
64955 fd5e51035335 issue 9910 Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 63674 diff changeset	199
fd5e51035335 issue 9910 Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 63674 diff changeset	200 .. index::
fd5e51035335 issue 9910 Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 63674 diff changeset	201 triple: module; search; path
fd5e51035335 issue 9910 Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 63674 diff changeset	202 single: path (in module sys)
fd5e51035335 issue 9910 Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 63674 diff changeset	203 single: Py_GetPath()
fd5e51035335 issue 9910 Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 63674 diff changeset	204
fd5e51035335 issue 9910 Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 63674 diff changeset	205 Set the default module search path. If this function is called before
65138 1cfd3b12489d Fix spelling and markup. Georg Brandl <georg@python.org> parents: 65137 diff changeset	206 :c:func:`Py_Initialize`, then :c:func:`Py_GetPath` won't attempt to compute a
1cfd3b12489d Fix spelling and markup. Georg Brandl <georg@python.org> parents: 65137 diff changeset	207 default search path but uses the one provided instead. This is useful if
1cfd3b12489d Fix spelling and markup. Georg Brandl <georg@python.org> parents: 65137 diff changeset	208 Python is embedded by an application that has full knowledge of the location
1cfd3b12489d Fix spelling and markup. Georg Brandl <georg@python.org> parents: 65137 diff changeset	209 of all modules. The path components should be separated by semicolons.
64955 fd5e51035335 issue 9910 Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 63674 diff changeset	210
65138 1cfd3b12489d Fix spelling and markup. Georg Brandl <georg@python.org> parents: 65137 diff changeset	211 This also causes :data:`sys.executable` to be set only to the raw program
1cfd3b12489d Fix spelling and markup. Georg Brandl <georg@python.org> parents: 65137 diff changeset	212 name (see :c:func:`Py_SetProgramName`) and for :data:`sys.prefix` and
1cfd3b12489d Fix spelling and markup. Georg Brandl <georg@python.org> parents: 65137 diff changeset	213 :data:`sys.exec_prefix` to be empty. It is up to the caller to modify these
1cfd3b12489d Fix spelling and markup. Georg Brandl <georg@python.org> parents: 65137 diff changeset	214 if required after calling :c:func:`Py_Initialize`.
1cfd3b12489d Fix spelling and markup. Georg Brandl <georg@python.org> parents: 65137 diff changeset	215
64955 fd5e51035335 issue 9910 Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 63674 diff changeset	216
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	217 .. c:function:: const char* Py_GetVersion()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219 Return the version of this Python interpreter. This is a string that looks
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	220 something like ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	221
46963 03b1233bf5fe Remove many "versionchanged" items that didn't use the official markup, Georg Brandl <georg@python.org> parents: 46318 diff changeset	222 "3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \n[GCC 4.2.3]"
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224 .. index:: single: version (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226 The first word (up to the first space character) is the current Python version;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227 the first three characters are the major and minor version separated by a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228 period. The returned string points into static storage; the caller should not
46963 03b1233bf5fe Remove many "versionchanged" items that didn't use the official markup, Georg Brandl <georg@python.org> parents: 46318 diff changeset	229 modify its value. The value is available to Python code as :data:`sys.version`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	232 .. c:function:: const char* Py_GetPlatform()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234 .. index:: single: platform (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236 Return the platform identifier for the current platform. On Unix, this is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237 formed from the "official" name of the operating system, converted to lower
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238 case, followed by the major revision number; e.g., for Solaris 2.x, which is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239 also known as SunOS 5.x, the value is ``'sunos5'``. On Mac OS X, it is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240 ``'darwin'``. On Windows, it is ``'win'``. The returned string points into
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241 static storage; the caller should not modify its value. The value is available
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242 to Python code as ``sys.platform``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	245 .. c:function:: const char* Py_GetCopyright()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247 Return the official copyright string for the current Python version, for example
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249 ``'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	251 .. index:: single: copyright (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	252
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253 The returned string points into static storage; the caller should not modify its
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	254 value. The value is available to Python code as ``sys.copyright``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	255
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	256
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	257 .. c:function:: const char* Py_GetCompiler()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	258
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259 Return an indication of the compiler used to build the current Python version,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260 in square brackets, for example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 "[GCC 2.7.2.2]"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264 .. index:: single: version (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266 The returned string points into static storage; the caller should not modify its
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	267 value. The value is available to Python code as part of the variable
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	268 ``sys.version``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	270
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	271 .. c:function:: const char* Py_GetBuildInfo()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	272
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273 Return information about the sequence number and build date and time of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	274 current Python interpreter instance, for example ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	275
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276 "#67, Aug 1 1997, 22:34:28"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	278 .. index:: single: version (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280 The returned string points into static storage; the caller should not modify its
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281 value. The value is available to Python code as part of the variable
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	282 ``sys.version``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	283
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	285 .. c:function:: void PySys_SetArgvEx(int argc, wchar_t **argv, int updatepath)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	287 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	288 single: main()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	289 single: Py_FatalError()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	290 single: argv (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	291
51382 7e28a2b0c1b1 Merged revisions 69129-69131,69139-69140,69143,69154-69159,69169,69288-69289,69293,69297-69301,69348 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50884 diff changeset	292 Set :data:`sys.argv` based on argc and argv. These parameters are
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	293 similar to those passed to the program's :c:func:`main` function with the
51382 7e28a2b0c1b1 Merged revisions 69129-69131,69139-69140,69143,69154-69159,69169,69288-69289,69293,69297-69301,69348 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50884 diff changeset	294 difference that the first entry should refer to the script file to be
7e28a2b0c1b1 Merged revisions 69129-69131,69139-69140,69143,69154-69159,69169,69288-69289,69293,69297-69301,69348 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50884 diff changeset	295 executed rather than the executable hosting the Python interpreter. If there
7e28a2b0c1b1 Merged revisions 69129-69131,69139-69140,69143,69154-69159,69169,69288-69289,69293,69297-69301,69348 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50884 diff changeset	296 isn't a script that will be run, the first entry in argv can be an empty
7e28a2b0c1b1 Merged revisions 69129-69131,69139-69140,69143,69154-69159,69169,69288-69289,69293,69297-69301,69348 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50884 diff changeset	297 string. If this function fails to initialize :data:`sys.argv`, a fatal
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	298 condition is signalled using :c:func:`Py_FatalError`.
51382 7e28a2b0c1b1 Merged revisions 69129-69131,69139-69140,69143,69154-69159,69169,69288-69289,69293,69297-69301,69348 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50884 diff changeset	299
61791 9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	300 If updatepath is zero, this is all the function does. If updatepath
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	301 is non-zero, the function also modifies :data:`sys.path` according to the
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	302 following algorithm:
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	303
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	304 - If the name of an existing script is passed in ``argv[0]``, the absolute
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	305 path of the directory where the script is located is prepended to
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	306 :data:`sys.path`.
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	307 - Otherwise (that is, if argc is 0 or ``argv[0]`` doesn't point
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	308 to an existing file name), an empty string is prepended to
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	309 :data:`sys.path`, which is the same as prepending the current working
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	310 directory (``"."``).
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	311
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	312 .. note::
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	313 It is recommended that applications embedding the Python interpreter
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	314 for purposes other than executing a single script pass 0 as updatepath,
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	315 and update :data:`sys.path` themselves if desired.
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	316 See `CVE-2008-5983 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983>`_.
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	317
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	318 On versions before 3.1.3, you can achieve the same effect by manually
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	319 popping the first :data:`sys.path` element after having called
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	320 :c:func:`PySys_SetArgv`, for example using::
61791 9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	321
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	322 PyRun_SimpleString("import sys; sys.path.pop(0)\n");
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	323
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	324 .. versionadded:: 3.1.3
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325
44396 6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44129 diff changeset	326 .. XXX impl. doesn't seem consistent in allowing 0/NULL for the params;
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44129 diff changeset	327 check w/ Guido.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	330 .. c:function:: void PySys_SetArgv(int argc, wchar_t **argv)
61791 9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	331
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	332 This function works like :c:func:`PySys_SetArgvEx` with updatepath set to 1.
61791 9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	333
9db8c414921f Merged revisions 81400 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 58219 diff changeset	334
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	335 .. c:function:: void Py_SetPythonHome(wchar_t *home)
51382 7e28a2b0c1b1 Merged revisions 69129-69131,69139-69140,69143,69154-69159,69169,69288-69289,69293,69297-69301,69348 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50884 diff changeset	336
7e28a2b0c1b1 Merged revisions 69129-69131,69139-69140,69143,69154-69159,69169,69288-69289,69293,69297-69301,69348 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50884 diff changeset	337 Set the default "home" directory, that is, the location of the standard
68007 b245d69b4f0a Merged revisions 86537,86867-86868,86881,86887,86913-86915,86931-86933,86960,86964,86974,86980,86996,87008,87050 via svnmerge from Georg Brandl <georg@python.org> parents: 67611 diff changeset	338 Python libraries. See :envvar:`PYTHONHOME` for the meaning of the
b245d69b4f0a Merged revisions 86537,86867-86868,86881,86887,86913-86915,86931-86933,86960,86964,86974,86980,86996,87008,87050 via svnmerge from Georg Brandl <georg@python.org> parents: 67611 diff changeset	339 argument string.
b245d69b4f0a Merged revisions 86537,86867-86868,86881,86887,86913-86915,86931-86933,86960,86964,86974,86980,86996,87008,87050 via svnmerge from Georg Brandl <georg@python.org> parents: 67611 diff changeset	340
56368 c9bd62efe6ce Merged revisions 75231 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55962 diff changeset	341 The argument should point to a zero-terminated character string in static
c9bd62efe6ce Merged revisions 75231 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55962 diff changeset	342 storage whose contents will not change for the duration of the program's
c9bd62efe6ce Merged revisions 75231 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55962 diff changeset	343 execution. No code in the Python interpreter will change the contents of
c9bd62efe6ce Merged revisions 75231 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55962 diff changeset	344 this storage.
51382 7e28a2b0c1b1 Merged revisions 69129-69131,69139-69140,69143,69154-69159,69169,69288-69289,69293,69297-69301,69348 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50884 diff changeset	345
7e28a2b0c1b1 Merged revisions 69129-69131,69139-69140,69143,69154-69159,69169,69288-69289,69293,69297-69301,69348 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50884 diff changeset	346
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	347 .. c:function:: w_char* Py_GetPythonHome()
51382 7e28a2b0c1b1 Merged revisions 69129-69131,69139-69140,69143,69154-69159,69169,69288-69289,69293,69297-69301,69348 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50884 diff changeset	348
7e28a2b0c1b1 Merged revisions 69129-69131,69139-69140,69143,69154-69159,69169,69288-69289,69293,69297-69301,69348 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50884 diff changeset	349 Return the default "home", that is, the value set by a previous call to
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	350 :c:func:`Py_SetPythonHome`, or the value of the :envvar:`PYTHONHOME`
51382 7e28a2b0c1b1 Merged revisions 69129-69131,69139-69140,69143,69154-69159,69169,69288-69289,69293,69297-69301,69348 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50884 diff changeset	351 environment variable if it is set.
7e28a2b0c1b1 Merged revisions 69129-69131,69139-69140,69143,69154-69159,69169,69288-69289,69293,69297-69301,69348 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50884 diff changeset	352
7e28a2b0c1b1 Merged revisions 69129-69131,69139-69140,69143,69154-69159,69169,69288-69289,69293,69297-69301,69348 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50884 diff changeset	353
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	354 .. _threads:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	355
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356 Thread State and the Global Interpreter Lock
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357 ============================================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360 single: global interpreter lock
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	361 single: interpreter lock
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362 single: lock, interpreter
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	363
66473 05ee6f8c0260 Merged revisions 85728,85731,85735,85766-85771,85773,85777 via svnmerge from Georg Brandl <georg@python.org> parents: 66470 diff changeset	364 The Python interpreter is not fully thread-safe. In order to support
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	365 multi-threaded Python programs, there's a global lock, called the :term:`global
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	366 interpreter lock` or :term:`GIL`, that must be held by the current thread before
53072 7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	367 it can safely access Python objects. Without the lock, even the simplest
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	368 operations could cause problems in a multi-threaded program: for example, when
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	369 two threads simultaneously increment the reference count of the same object, the
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	370 reference count could end up being incremented only once instead of twice.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	371
67609 f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	372 .. index:: single: setswitchinterval() (in module sys)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	373
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	374 Therefore, the rule exists that only the thread that has acquired the
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	375 :term:`GIL` may operate on Python objects or call Python/C API functions.
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	376 In order to emulate concurrency of execution, the interpreter regularly
67609 f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	377 tries to switch threads (see :func:`sys.setswitchinterval`). The lock is also
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	378 released around potentially blocking I/O operations like reading or writing
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	379 a file, so that other Python threads can run in the meantime.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	380
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	381 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	382 single: PyThreadState
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	383 single: PyThreadState
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	384
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	385 The Python interpreter keeps some thread-specific bookkeeping information
67609 f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	386 inside a data structure called :c:type:`PyThreadState`. There's also one
f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	387 global variable pointing to the current :c:type:`PyThreadState`: it can
f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	388 be retrieved using :c:func:`PyThreadState_Get`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	389
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	390 Releasing the GIL from extension code
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	391 -------------------------------------
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	392
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	393 Most extension code manipulating the :term:`GIL` has the following simple
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	394 structure::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	395
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396 Save the thread state in a local variable.
53072 7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	397 Release the global interpreter lock.
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	398 ... Do some blocking I/O operation ...
53072 7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	399 Reacquire the global interpreter lock.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	400 Restore the thread state from the local variable.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	401
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	402 This is so common that a pair of macros exists to simplify it::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	403
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	404 Py_BEGIN_ALLOW_THREADS
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	405 ... Do some blocking I/O operation ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	406 Py_END_ALLOW_THREADS
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	407
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	409 single: Py_BEGIN_ALLOW_THREADS
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	410 single: Py_END_ALLOW_THREADS
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	412 The :c:macro:`Py_BEGIN_ALLOW_THREADS` macro opens a new block and declares a
521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	413 hidden local variable; the :c:macro:`Py_END_ALLOW_THREADS` macro closes the
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	414 block. These two macros are still available when Python is compiled without
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	415 thread support (they simply have an empty expansion).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	416
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417 When thread support is enabled, the block above expands to the following code::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	418
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	419 PyThreadState *_save;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	420
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	421 _save = PyEval_SaveThread();
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	422 ...Do some blocking I/O operation...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	423 PyEval_RestoreThread(_save);
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	424
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	425 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	426 single: PyEval_RestoreThread()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427 single: PyEval_SaveThread()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	429 Here is how these functions work: the global interpreter lock is used to protect the pointer to the
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	430 current thread state. When releasing the lock and saving the thread state,
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	431 the current thread state pointer must be retrieved before the lock is released
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	432 (since another thread could immediately acquire the lock and store its own thread
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	433 state in the global variable). Conversely, when acquiring the lock and restoring
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	434 the thread state, the lock must be acquired before storing the thread state
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	435 pointer.
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	436
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	437 .. note::
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	438 Calling system I/O functions is the most common use case for releasing
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	439 the GIL, but it can also be useful before calling long-running computations
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	440 which don't need access to Python objects, such as compression or
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	441 cryptographic functions operating over memory buffers. For example, the
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	442 standard :mod:`zlib` and :mod:`hashlib` modules release the GIL when
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	443 compressing or hashing data.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	444
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	445 Non-Python created threads
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	446 --------------------------
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	447
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	448 When threads are created using the dedicated Python APIs (such as the
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	449 :mod:`threading` module), a thread state is automatically associated to them
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	450 and the code showed above is therefore correct. However, when threads are
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	451 created from C (for example by a third-party library with its own thread
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	452 management), they don't hold the GIL, nor is there a thread state structure
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	453 for them.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	454
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	455 If you need to call Python code from these threads (often this will be part
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	456 of a callback API provided by the aforementioned third-party library),
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	457 you must first register these threads with the interpreter by
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	458 creating a thread state data structure, then acquiring the GIL, and finally
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	459 storing their thread state pointer, before you can start using the Python/C
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	460 API. When you are done, you should reset the thread state pointer, release
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	461 the GIL, and finally free the thread state data structure.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	462
67609 f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	463 The :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` functions do
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	464 all of the above automatically. The typical idiom for calling into Python
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	465 from a C thread is::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	466
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	467 PyGILState_STATE gstate;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	468 gstate = PyGILState_Ensure();
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	469
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	470 /* Perform Python actions here. */
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	471 result = CallSomeFunction();
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	472 /* evaluate result or handle exception */
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	473
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	474 /* Release the thread. No Python API allowed beyond this point. */
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	475 PyGILState_Release(gstate);
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	476
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	477 Note that the :c:func:`PyGILState_\*` functions assume there is only one global
67609 f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	478 interpreter (created automatically by :c:func:`Py_Initialize`). Python
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	479 supports the creation of additional interpreters (using
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	480 :c:func:`Py_NewInterpreter`), but mixing multiple interpreters and the
521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	481 :c:func:`PyGILState_\*` API is unsupported.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	482
56382 2e4d7a40c2dd Merged revisions 75246 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 56368 diff changeset	483 Another important thing to note about threads is their behaviour in the face
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	484 of the C :c:func:`fork` call. On most systems with :c:func:`fork`, after a
56382 2e4d7a40c2dd Merged revisions 75246 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 56368 diff changeset	485 process forks only the thread that issued the fork will exist. That also
2e4d7a40c2dd Merged revisions 75246 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 56368 diff changeset	486 means any locks held by other threads will never be released. Python solves
2e4d7a40c2dd Merged revisions 75246 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 56368 diff changeset	487 this for :func:`os.fork` by acquiring the locks it uses internally before
2e4d7a40c2dd Merged revisions 75246 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 56368 diff changeset	488 the fork, and releasing them afterwards. In addition, it resets any
2e4d7a40c2dd Merged revisions 75246 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 56368 diff changeset	489 :ref:`lock-objects` in the child. When extending or embedding Python, there
2e4d7a40c2dd Merged revisions 75246 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 56368 diff changeset	490 is no way to inform Python of additional (non-Python) locks that need to be
2e4d7a40c2dd Merged revisions 75246 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 56368 diff changeset	491 acquired before or reset after a fork. OS facilities such as
69477 a2a2882ce6b4 Merge with 3.1. Ezio Melotti <ezio.melotti@gmail.com> parents: 69419 69476 diff changeset	492 :c:func:`pthread_atfork` would need to be used to accomplish the same thing.
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	493 Additionally, when extending or embedding Python, calling :c:func:`fork`
56382 2e4d7a40c2dd Merged revisions 75246 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 56368 diff changeset	494 directly rather than through :func:`os.fork` (and returning to or calling
2e4d7a40c2dd Merged revisions 75246 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 56368 diff changeset	495 into Python) may result in a deadlock by one of Python's internal locks
2e4d7a40c2dd Merged revisions 75246 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 56368 diff changeset	496 being held by a thread that is defunct after the fork.
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	497 :c:func:`PyOS_AfterFork` tries to reset the necessary locks, but is not
56382 2e4d7a40c2dd Merged revisions 75246 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 56368 diff changeset	498 always able to.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	500
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	501 High-level API
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	502 --------------
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	503
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	504 These are the most commonly used types and functions when writing C extension
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	505 code, or when embedding the Python interpreter:
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	506
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	507 .. c:type:: PyInterpreterState
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	508
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	509 This data structure represents the state shared by a number of cooperating
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	510 threads. Threads belonging to the same interpreter share their module
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	511 administration and a few other internal items. There are no public members in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	512 this structure.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	513
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	514 Threads belonging to different interpreters initially share nothing, except
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	515 process state like available memory, open file descriptors and such. The global
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	516 interpreter lock is also shared by all threads, regardless of to which
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	517 interpreter they belong.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	518
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	519
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	520 .. c:type:: PyThreadState
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	521
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	522 This data structure represents the state of a single thread. The only public
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	523 data member is :c:type:`PyInterpreterState \*`:attr:`interp`, which points to
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	524 this thread's interpreter state.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	525
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	526
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	527 .. c:function:: void PyEval_InitThreads()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	528
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	529 .. index::
67613 b8f97d8cd485 Nits Antoine Pitrou <solipsis@pitrou.net> parents: 67610 diff changeset	530 single: PyEval_AcquireThread()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	531 single: PyEval_ReleaseThread()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	532 single: PyEval_SaveThread()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	533 single: PyEval_RestoreThread()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	534
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	535 Initialize and acquire the global interpreter lock. It should be called in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	536 main thread before creating a second thread or engaging in any other thread
67613 b8f97d8cd485 Nits Antoine Pitrou <solipsis@pitrou.net> parents: 67610 diff changeset	537 operations such as ``PyEval_ReleaseThread(tstate)``. It is not needed before
b8f97d8cd485 Nits Antoine Pitrou <solipsis@pitrou.net> parents: 67610 diff changeset	538 calling :c:func:`PyEval_SaveThread` or :c:func:`PyEval_RestoreThread`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	539
68511 2c57a8f293ba Followup to 4c59cd84086f: add an entry in the porting guide and a "versionchanged" attribute. Antoine Pitrou <solipsis@pitrou.net> parents: 68429 diff changeset	540 This is a no-op when called for a second time.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	541
68511 2c57a8f293ba Followup to 4c59cd84086f: add an entry in the porting guide and a "versionchanged" attribute. Antoine Pitrou <solipsis@pitrou.net> parents: 68429 diff changeset	542 .. versionchanged:: 3.2
2c57a8f293ba Followup to 4c59cd84086f: add an entry in the porting guide and a "versionchanged" attribute. Antoine Pitrou <solipsis@pitrou.net> parents: 68429 diff changeset	543 This function cannot be called before :c:func:`Py_Initialize()` anymore.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	544
47266 7fe3a8648ce2 Rename thread to _thread and dummy_thread to _dummy_thread. Issue #2875. Georg Brandl <georg@python.org> parents: 46963 diff changeset	545 .. index:: module: _thread
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	546
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	547 .. note::
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	548 When only the main thread exists, no GIL operations are needed. This is a
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	549 common situation (most Python programs do not use threads), and the lock
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	550 operations slow the interpreter down a bit. Therefore, the lock is not
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	551 created initially. This situation is equivalent to having acquired the lock:
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	552 when there is only a single thread, all object accesses are safe. Therefore,
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	553 when this function initializes the global interpreter lock, it also acquires
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	554 it. Before the Python :mod:`_thread` module creates a new thread, knowing
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	555 that either it has the lock or the lock hasn't been created yet, it calls
67609 f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	556 :c:func:`PyEval_InitThreads`. When this call returns, it is guaranteed that
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	557 the lock has been created and that the calling thread has acquired it.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	558
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	559 It is not safe to call this function when it is unknown which thread (if
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	560 any) currently has the global interpreter lock.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	561
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	562 This function is not available when thread support is disabled at compile time.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	563
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	564
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	565 .. c:function:: int PyEval_ThreadsInitialized()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	566
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	567 Returns a non-zero value if :c:func:`PyEval_InitThreads` has been called. This
53072 7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	568 function can be called without holding the GIL, and therefore can be used to
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	569 avoid calls to the locking API when running single-threaded. This function is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	570 not available when thread support is disabled at compile time.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	571
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	572
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	573 .. c:function:: PyThreadState* PyEval_SaveThread()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	574
53072 7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	575 Release the global interpreter lock (if it has been created and thread
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	576 support is enabled) and reset the thread state to NULL, returning the
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	577 previous thread state (which is not NULL). If the lock has been created,
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	578 the current thread must have acquired it. (This function is available even
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	579 when thread support is disabled at compile time.)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	580
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	581
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	582 .. c:function:: void PyEval_RestoreThread(PyThreadState *tstate)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	583
53072 7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	584 Acquire the global interpreter lock (if it has been created and thread
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	585 support is enabled) and set the thread state to tstate, which must not be
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	586 NULL. If the lock has been created, the current thread must not have
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	587 acquired it, otherwise deadlock ensues. (This function is available even
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	588 when thread support is disabled at compile time.)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	589
44104 ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	590
67609 f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	591 .. c:function:: PyThreadState* PyThreadState_Get()
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	592
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	593 Return the current thread state. The global interpreter lock must be held.
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	594 When the current thread state is NULL, this issues a fatal error (so that
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	595 the caller needn't check for NULL).
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	596
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	597
67609 f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	598 .. c:function:: PyThreadState* PyThreadState_Swap(PyThreadState *tstate)
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	599
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	600 Swap the current thread state with the thread state given by the argument
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	601 tstate, which may be NULL. The global interpreter lock must be held
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	602 and is not released.
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	603
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	604
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	605 .. c:function:: void PyEval_ReInitThreads()
44104 ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	606
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	607 This function is called from :c:func:`PyOS_AfterFork` to ensure that newly
44104 ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	608 created child processes don't hold locks referring to threads which
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	609 are not running in the child process.
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	610
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	611
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	612 The following functions use thread-local storage, and are not compatible
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	613 with sub-interpreters:
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	614
67609 f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	615 .. c:function:: PyGILState_STATE PyGILState_Ensure()
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	616
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	617 Ensure that the current thread is ready to call the Python C API regardless
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	618 of the current state of Python, or of the global interpreter lock. This may
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	619 be called as many times as desired by a thread as long as each call is
67609 f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	620 matched with a call to :c:func:`PyGILState_Release`. In general, other
f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	621 thread-related APIs may be used between :c:func:`PyGILState_Ensure` and
f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	622 :c:func:`PyGILState_Release` calls as long as the thread state is restored to
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	623 its previous state before the Release(). For example, normal usage of the
67609 f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	624 :c:macro:`Py_BEGIN_ALLOW_THREADS` and :c:macro:`Py_END_ALLOW_THREADS` macros is
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	625 acceptable.
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	626
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	627 The return value is an opaque "handle" to the thread state when
67609 f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	628 :c:func:`PyGILState_Ensure` was called, and must be passed to
f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	629 :c:func:`PyGILState_Release` to ensure Python is left in the same state. Even
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	630 though recursive calls are allowed, these handles cannot be shared - each
67609 f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	631 unique call to :c:func:`PyGILState_Ensure` must save the handle for its call
f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	632 to :c:func:`PyGILState_Release`.
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	633
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	634 When the function returns, the current thread will hold the GIL and be able
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	635 to call arbitrary Python code. Failure is a fatal error.
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	636
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	637
67609 f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	638 .. c:function:: void PyGILState_Release(PyGILState_STATE)
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	639
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	640 Release any resources previously acquired. After this call, Python's state will
67609 f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	641 be the same as it was prior to the corresponding :c:func:`PyGILState_Ensure` call
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	642 (but generally this state will be unknown to the caller, hence the use of the
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	643 GILState API).
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	644
67609 f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	645 Every call to :c:func:`PyGILState_Ensure` must be matched by a call to
f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	646 :c:func:`PyGILState_Release` on the same thread.
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	647
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	648
71769 53b8260b9ea7 #10741: add documentation for PyGILState_GetThisThreadState() Sandro Tosi <sandro.tosi@gmail.com> parents: 69844 diff changeset	649 .. c:function:: PyThreadState PyGILState_GetThisThreadState()
53b8260b9ea7 #10741: add documentation for PyGILState_GetThisThreadState() Sandro Tosi <sandro.tosi@gmail.com> parents: 69844 diff changeset	650
53b8260b9ea7 #10741: add documentation for PyGILState_GetThisThreadState() Sandro Tosi <sandro.tosi@gmail.com> parents: 69844 diff changeset	651 Get the current thread state for this thread. May return ``NULL`` if no
53b8260b9ea7 #10741: add documentation for PyGILState_GetThisThreadState() Sandro Tosi <sandro.tosi@gmail.com> parents: 69844 diff changeset	652 GILState API has been used on the current thread. Note that the main thread
53b8260b9ea7 #10741: add documentation for PyGILState_GetThisThreadState() Sandro Tosi <sandro.tosi@gmail.com> parents: 69844 diff changeset	653 always has such a thread-state, even if no auto-thread-state call has been
53b8260b9ea7 #10741: add documentation for PyGILState_GetThisThreadState() Sandro Tosi <sandro.tosi@gmail.com> parents: 69844 diff changeset	654 made on the main thread. This is mainly a helper/diagnostic function.
53b8260b9ea7 #10741: add documentation for PyGILState_GetThisThreadState() Sandro Tosi <sandro.tosi@gmail.com> parents: 69844 diff changeset	655
53b8260b9ea7 #10741: add documentation for PyGILState_GetThisThreadState() Sandro Tosi <sandro.tosi@gmail.com> parents: 69844 diff changeset	656
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	657 The following macros are normally used without a trailing semicolon; look for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	658 example usage in the Python source distribution.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	659
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	660
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	661 .. c:macro:: Py_BEGIN_ALLOW_THREADS
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	662
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	663 This macro expands to ``{ PyThreadState *_save; _save = PyEval_SaveThread();``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	664 Note that it contains an opening brace; it must be matched with a following
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	665 :c:macro:`Py_END_ALLOW_THREADS` macro. See above for further discussion of this
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	666 macro. It is a no-op when thread support is disabled at compile time.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	667
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	668
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	669 .. c:macro:: Py_END_ALLOW_THREADS
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	670
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	671 This macro expands to ``PyEval_RestoreThread(_save); }``. Note that it contains
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	672 a closing brace; it must be matched with an earlier
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	673 :c:macro:`Py_BEGIN_ALLOW_THREADS` macro. See above for further discussion of
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	674 this macro. It is a no-op when thread support is disabled at compile time.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	675
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	676
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	677 .. c:macro:: Py_BLOCK_THREADS
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	678
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	679 This macro expands to ``PyEval_RestoreThread(_save);``: it is equivalent to
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	680 :c:macro:`Py_END_ALLOW_THREADS` without the closing brace. It is a no-op when
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	681 thread support is disabled at compile time.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	682
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	683
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	684 .. c:macro:: Py_UNBLOCK_THREADS
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	685
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	686 This macro expands to ``_save = PyEval_SaveThread();``: it is equivalent to
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	687 :c:macro:`Py_BEGIN_ALLOW_THREADS` without the opening brace and variable
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	688 declaration. It is a no-op when thread support is disabled at compile time.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	689
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	690
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	691 Low-level API
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	692 -------------
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	693
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	694 All of the following functions are only available when thread support is enabled
53072 7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	695 at compile time, and must be called only when the global interpreter lock has
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	696 been created.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	697
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	698
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	699 .. c:function:: PyInterpreterState* PyInterpreterState_New()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	700
53072 7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	701 Create a new interpreter state object. The global interpreter lock need not
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	702 be held, but may be held if it is necessary to serialize calls to this
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	703 function.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	704
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	705
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	706 .. c:function:: void PyInterpreterState_Clear(PyInterpreterState *interp)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	707
53072 7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	708 Reset all information in an interpreter state object. The global interpreter
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	709 lock must be held.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	710
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	711
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	712 .. c:function:: void PyInterpreterState_Delete(PyInterpreterState *interp)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	713
53072 7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	714 Destroy an interpreter state object. The global interpreter lock need not be
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	715 held. The interpreter state must have been reset with a previous call to
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	716 :c:func:`PyInterpreterState_Clear`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	717
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	718
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	719 .. c:function:: PyThreadState* PyThreadState_New(PyInterpreterState *interp)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	720
53072 7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	721 Create a new thread state object belonging to the given interpreter object.
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	722 The global interpreter lock need not be held, but may be held if it is
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	723 necessary to serialize calls to this function.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	724
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	725
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	726 .. c:function:: void PyThreadState_Clear(PyThreadState *tstate)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	727
53072 7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	728 Reset all information in a thread state object. The global interpreter lock
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	729 must be held.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	730
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	731
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	732 .. c:function:: void PyThreadState_Delete(PyThreadState *tstate)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	733
53072 7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	734 Destroy a thread state object. The global interpreter lock need not be held.
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	735 The thread state must have been reset with a previous call to
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	736 :c:func:`PyThreadState_Clear`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	737
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	738
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	739 .. c:function:: PyObject* PyThreadState_GetDict()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	740
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	741 Return a dictionary in which extensions can store thread-specific state
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	742 information. Each extension should use a unique key to use to store state in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	743 the dictionary. It is okay to call this function when no current thread state
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	744 is available. If this function returns NULL, no exception has been raised and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	745 the caller should assume no current thread state is available.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	746
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	747
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	748 .. c:function:: int PyThreadState_SetAsyncExc(long id, PyObject *exc)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	749
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	750 Asynchronously raise an exception in a thread. The id argument is the thread
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	751 id of the target thread; exc is the exception object to be raised. This
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	752 function does not steal any references to exc. To prevent naive misuse, you
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	753 must write your own C extension to call this. Must be called with the GIL held.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	754 Returns the number of thread states modified; this is normally one, but will be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	755 zero if the thread id isn't found. If exc is :const:`NULL`, the pending
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	756 exception (if any) for the thread is cleared. This raises no exceptions.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	757
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	758
67609 f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	759 .. c:function:: void PyEval_AcquireThread(PyThreadState *tstate)
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	760
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	761 Acquire the global interpreter lock and set the current thread state to
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	762 tstate, which should not be NULL. The lock must have been created earlier.
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	763 If this thread already has the lock, deadlock ensues.
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	764
67610 beeab0fa41e5 Issue #10913: Deprecate misleading functions PyEval_AcquireLock() and Antoine Pitrou <solipsis@pitrou.net> parents: 67609 diff changeset	765 :c:func:`PyEval_RestoreThread` is a higher-level function which is always
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	766 available (even when thread support isn't enabled or when threads have
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	767 not been initialized).
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	768
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	769
67609 f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	770 .. c:function:: void PyEval_ReleaseThread(PyThreadState *tstate)
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	771
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	772 Reset the current thread state to NULL and release the global interpreter
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	773 lock. The lock must have been created earlier and must be held by the current
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	774 thread. The tstate argument, which must not be NULL, is only used to check
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	775 that it represents the current thread state --- if it isn't, a fatal error is
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	776 reported.
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	777
67610 beeab0fa41e5 Issue #10913: Deprecate misleading functions PyEval_AcquireLock() and Antoine Pitrou <solipsis@pitrou.net> parents: 67609 diff changeset	778 :c:func:`PyEval_SaveThread` is a higher-level function which is always
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	779 available (even when thread support isn't enabled or when threads have
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	780 not been initialized).
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	781
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	782
67609 f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	783 .. c:function:: void PyEval_AcquireLock()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	784
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	785 Acquire the global interpreter lock. The lock must have been created earlier.
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	786 If this thread already has the lock, a deadlock ensues.
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	787
67610 beeab0fa41e5 Issue #10913: Deprecate misleading functions PyEval_AcquireLock() and Antoine Pitrou <solipsis@pitrou.net> parents: 67609 diff changeset	788 .. deprecated:: 3.2
67613 b8f97d8cd485 Nits Antoine Pitrou <solipsis@pitrou.net> parents: 67610 diff changeset	789 This function does not update the current thread state. Please use
67610 beeab0fa41e5 Issue #10913: Deprecate misleading functions PyEval_AcquireLock() and Antoine Pitrou <solipsis@pitrou.net> parents: 67609 diff changeset	790 :c:func:`PyEval_RestoreThread` or :c:func:`PyEval_AcquireThread`
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	791 instead.
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	792
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	793
67609 f130be01d230 Reword and restructure the GIL API doc Antoine Pitrou <solipsis@pitrou.net> parents: 67608 diff changeset	794 .. c:function:: void PyEval_ReleaseLock()
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	795
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	796 Release the global interpreter lock. The lock must have been created earlier.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	797
67610 beeab0fa41e5 Issue #10913: Deprecate misleading functions PyEval_AcquireLock() and Antoine Pitrou <solipsis@pitrou.net> parents: 67609 diff changeset	798 .. deprecated:: 3.2
67613 b8f97d8cd485 Nits Antoine Pitrou <solipsis@pitrou.net> parents: 67610 diff changeset	799 This function does not update the current thread state. Please use
67610 beeab0fa41e5 Issue #10913: Deprecate misleading functions PyEval_AcquireLock() and Antoine Pitrou <solipsis@pitrou.net> parents: 67609 diff changeset	800 :c:func:`PyEval_SaveThread` or :c:func:`PyEval_ReleaseThread`
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	801 instead.
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	802
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	803
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	804 Sub-interpreter support
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	805 =======================
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	806
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	807 While in most uses, you will only embed a single Python interpreter, there
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	808 are cases where you need to create several independent interpreters in the
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	809 same process and perhaps even in the same thread. Sub-interpreters allow
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	810 you to do that. You can switch between sub-interpreters using the
67608 93b7c0580c43 Add mention of how to switch interpreters Antoine Pitrou <solipsis@pitrou.net> parents: 67607 diff changeset	811 :c:func:`PyThreadState_Swap` function. You can create and destroy them
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	812 using the following functions:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	813
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	814
67606 3969a6ca16af Restructure a bit Antoine Pitrou <solipsis@pitrou.net> parents: 67605 diff changeset	815 .. c:function:: PyThreadState* Py_NewInterpreter()
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	816
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	817 .. index::
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	818 module: builtins
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	819 module: __main__
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	820 module: sys
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	821 single: stdout (in module sys)
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	822 single: stderr (in module sys)
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	823 single: stdin (in module sys)
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	824
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	825 Create a new sub-interpreter. This is an (almost) totally separate environment
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	826 for the execution of Python code. In particular, the new interpreter has
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	827 separate, independent versions of all imported modules, including the
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	828 fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`. The
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	829 table of loaded modules (``sys.modules``) and the module search path
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	830 (``sys.path``) are also separate. The new environment has no ``sys.argv``
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	831 variable. It has new standard I/O stream file objects ``sys.stdin``,
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	832 ``sys.stdout`` and ``sys.stderr`` (however these refer to the same underlying
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	833 file descriptors).
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	834
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	835 The return value points to the first thread state created in the new
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	836 sub-interpreter. This thread state is made in the current thread state.
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	837 Note that no actual thread is created; see the discussion of thread states
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	838 below. If creation of the new interpreter is unsuccessful, NULL is
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	839 returned; no exception is set since the exception state is stored in the
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	840 current thread state and there may not be a current thread state. (Like all
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	841 other Python/C API functions, the global interpreter lock must be held before
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	842 calling this function and is still held when it returns; however, unlike most
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	843 other Python/C API functions, there needn't be a current thread state on
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	844 entry.)
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	845
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	846 .. index::
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	847 single: Py_Finalize()
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	848 single: Py_Initialize()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	849
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	850 Extension modules are shared between (sub-)interpreters as follows: the first
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	851 time a particular extension is imported, it is initialized normally, and a
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	852 (shallow) copy of its module's dictionary is squirreled away. When the same
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	853 extension is imported by another (sub-)interpreter, a new module is initialized
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	854 and filled with the contents of this copy; the extension's ``init`` function is
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	855 not called. Note that this is different from what happens when an extension is
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	856 imported after the interpreter has been completely re-initialized by calling
67606 3969a6ca16af Restructure a bit Antoine Pitrou <solipsis@pitrou.net> parents: 67605 diff changeset	857 :c:func:`Py_Finalize` and :c:func:`Py_Initialize`; in that case, the extension's
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	858 ``initmodule`` function is called again.
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	859
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	860 .. index:: single: close() (in module os)
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	861
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	862
67606 3969a6ca16af Restructure a bit Antoine Pitrou <solipsis@pitrou.net> parents: 67605 diff changeset	863 .. c:function:: void Py_EndInterpreter(PyThreadState *tstate)
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	864
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	865 .. index:: single: Py_Finalize()
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	866
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	867 Destroy the (sub-)interpreter represented by the given thread state. The given
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	868 thread state must be the current thread state. See the discussion of thread
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	869 states below. When the call returns, the current thread state is NULL. All
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	870 thread states associated with this interpreter are destroyed. (The global
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	871 interpreter lock must be held before calling this function and is still held
67606 3969a6ca16af Restructure a bit Antoine Pitrou <solipsis@pitrou.net> parents: 67605 diff changeset	872 when it returns.) :c:func:`Py_Finalize` will destroy all sub-interpreters that
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	873 haven't been explicitly destroyed at that point.
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	874
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	875
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	876 Bugs and caveats
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	877 ----------------
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	878
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	879 Because sub-interpreters (and the main interpreter) are part of the same
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	880 process, the insulation between them isn't perfect --- for example, using
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	881 low-level file operations like :func:`os.close` they can
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	882 (accidentally or maliciously) affect each other's open files. Because of the
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	883 way extensions are shared between (sub-)interpreters, some extensions may not
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	884 work properly; this is especially likely when the extension makes use of
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	885 (static) global variables, or when the extension manipulates its module's
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	886 dictionary after its initialization. It is possible to insert objects created
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	887 in one sub-interpreter into a namespace of another sub-interpreter; this should
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	888 be done with great care to avoid sharing user-defined functions, methods,
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	889 instances or classes between sub-interpreters, since import operations executed
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	890 by such objects may affect the wrong (sub-)interpreter's dictionary of loaded
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	891 modules.
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	892
67607 3f99c36d00b8 Improve description of issues Antoine Pitrou <solipsis@pitrou.net> parents: 67606 diff changeset	893 Also note that combining this functionality with :c:func:`PyGILState_\*` APIs
69843 3aa51217492c #11997: fix typo in init.rst. Ezio Melotti <ezio.melotti@gmail.com> parents: 69640 diff changeset	894 is delicate, because these APIs assume a bijection between Python thread states
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	895 and OS-level threads, an assumption broken by the presence of sub-interpreters.
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	896 It is highly recommended that you don't switch sub-interpreters between a pair
67607 3f99c36d00b8 Improve description of issues Antoine Pitrou <solipsis@pitrou.net> parents: 67606 diff changeset	897 of matching :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` calls.
67611 b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	898 Furthermore, extensions (such as :mod:`ctypes`) using these APIs to allow calling
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	899 of Python code from non-Python created threads will probably be broken when using
b03747ada44d Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66473 diff changeset	900 sub-interpreters.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	901
50758 2c03c7580aa3 Merged revisions 68425,68461,68498 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	902
2c03c7580aa3 Merged revisions 68425,68461,68498 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	903 Asynchronous Notifications
2c03c7580aa3 Merged revisions 68425,68461,68498 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	904 ==========================
2c03c7580aa3 Merged revisions 68425,68461,68498 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	905
52892 792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52144 diff changeset	906 A mechanism is provided to make asynchronous notifications to the main
50758 2c03c7580aa3 Merged revisions 68425,68461,68498 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	907 interpreter thread. These notifications take the form of a function
2c03c7580aa3 Merged revisions 68425,68461,68498 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	908 pointer and a void argument.
2c03c7580aa3 Merged revisions 68425,68461,68498 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	909
2c03c7580aa3 Merged revisions 68425,68461,68498 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	910 .. index:: single: setcheckinterval() (in module sys)
2c03c7580aa3 Merged revisions 68425,68461,68498 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	911
53072 7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	912 Every check interval, when the global interpreter lock is released and
57798 e23f5ec93315 Merged revisions 76906 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56382 diff changeset	913 reacquired, Python will also call any such provided functions. This can be used
53072 7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	914 for example by asynchronous IO handlers. The notification can be scheduled from
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	915 a worker thread and the actual call than made at the earliest convenience by the
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	916 main thread where it has possession of the global interpreter lock and can
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	917 perform any Python API calls.
50758 2c03c7580aa3 Merged revisions 68425,68461,68498 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	918
69641 119c7219b1ac #11942: merge with 3.1. Ezio Melotti <ezio.melotti@gmail.com> parents: 69477 69640 diff changeset	919 .. c:function:: int Py_AddPendingCall(int (func)(void ), void *arg)
50758 2c03c7580aa3 Merged revisions 68425,68461,68498 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	920
2c03c7580aa3 Merged revisions 68425,68461,68498 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	921 .. index:: single: Py_AddPendingCall()
2c03c7580aa3 Merged revisions 68425,68461,68498 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	922
53072 7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	923 Post a notification to the Python main thread. If successful, func will be
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	924 called with the argument arg at the earliest convenience. func will be
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	925 called having the global interpreter lock held and can thus use the full
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	926 Python API and can take any action such as setting object attributes to
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	927 signal IO completion. It must return 0 on success, or -1 signalling an
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	928 exception. The notification function won't be interrupted to perform another
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	929 asynchronous notification recursively, but it can still be interrupted to
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	930 switch threads if the global interpreter lock is released, for example, if it
57798 e23f5ec93315 Merged revisions 76906 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56382 diff changeset	931 calls back into Python code.
50758 2c03c7580aa3 Merged revisions 68425,68461,68498 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	932
2c03c7580aa3 Merged revisions 68425,68461,68498 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	933 This function returns 0 on success in which case the notification has been
53072 7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	934 scheduled. Otherwise, for example if the notification buffer is full, it
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	935 returns -1 without setting any exception.
50758 2c03c7580aa3 Merged revisions 68425,68461,68498 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	936
53072 7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	937 This function can be called on any thread, be it a Python thread or some
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	938 other system thread. If it is a Python thread, it doesn't matter if it holds
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52892 diff changeset	939 the global interpreter lock or not.
50758 2c03c7580aa3 Merged revisions 68425,68461,68498 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	940
53784 f6bffb9e834f 2.7 -> 3.1 versionchanges. Georg Brandl <georg@python.org> parents: 53483 diff changeset	941 .. versionadded:: 3.1
50758 2c03c7580aa3 Merged revisions 68425,68461,68498 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	942
2c03c7580aa3 Merged revisions 68425,68461,68498 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	943
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	944 .. _profiling:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	945
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	946 Profiling and Tracing
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	947 =====================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	948
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	949 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	950
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	951
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	952 The Python interpreter provides some low-level support for attaching profiling
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	953 and execution tracing facilities. These are used for profiling, debugging, and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	954 coverage analysis tools.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	955
46963 03b1233bf5fe Remove many "versionchanged" items that didn't use the official markup, Georg Brandl <georg@python.org> parents: 46318 diff changeset	956 This C interface allows the profiling or tracing code to avoid the overhead of
03b1233bf5fe Remove many "versionchanged" items that didn't use the official markup, Georg Brandl <georg@python.org> parents: 46318 diff changeset	957 calling through Python-level callable objects, making a direct C function call
03b1233bf5fe Remove many "versionchanged" items that didn't use the official markup, Georg Brandl <georg@python.org> parents: 46318 diff changeset	958 instead. The essential attributes of the facility have not changed; the
03b1233bf5fe Remove many "versionchanged" items that didn't use the official markup, Georg Brandl <georg@python.org> parents: 46318 diff changeset	959 interface allows trace functions to be installed per-thread, and the basic
03b1233bf5fe Remove many "versionchanged" items that didn't use the official markup, Georg Brandl <georg@python.org> parents: 46318 diff changeset	960 events reported to the trace function are the same as had been reported to the
03b1233bf5fe Remove many "versionchanged" items that didn't use the official markup, Georg Brandl <georg@python.org> parents: 46318 diff changeset	961 Python-level trace functions in previous versions.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	962
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	963
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	964 .. c:type:: int (Py_tracefunc)(PyObject obj, PyFrameObject frame, int what, PyObject arg)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	965
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	966 The type of the trace function registered using :c:func:`PyEval_SetProfile` and
521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	967 :c:func:`PyEval_SetTrace`. The first parameter is the object passed to the
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	968 registration function as obj, frame is the frame object to which the event
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	969 pertains, what is one of the constants :const:`PyTrace_CALL`,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	970 :const:`PyTrace_EXCEPTION`, :const:`PyTrace_LINE`, :const:`PyTrace_RETURN`,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	971 :const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION`, or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	972 :const:`PyTrace_C_RETURN`, and arg depends on the value of what:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	973
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	974 +------------------------------+--------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	975 \| Value of what \| Meaning of arg \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	976 +==============================+======================================+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	977 \| :const:`PyTrace_CALL` \| Always NULL. \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	978 +------------------------------+--------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	979 \| :const:`PyTrace_EXCEPTION` \| Exception information as returned by \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	980 \| \| :func:`sys.exc_info`. \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	981 +------------------------------+--------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	982 \| :const:`PyTrace_LINE` \| Always NULL. \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	983 +------------------------------+--------------------------------------+
66470 45e49269e0d8 Merged revisions 85530,85532-85534,85538-85543,85546-85548 via svnmerge from Georg Brandl <georg@python.org> parents: 65116 diff changeset	984 \| :const:`PyTrace_RETURN` \| Value being returned to the caller, \|
45e49269e0d8 Merged revisions 85530,85532-85534,85538-85543,85546-85548 via svnmerge from Georg Brandl <georg@python.org> parents: 65116 diff changeset	985 \| \| or NULL if caused by an exception. \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	986 +------------------------------+--------------------------------------+
66470 45e49269e0d8 Merged revisions 85530,85532-85534,85538-85543,85546-85548 via svnmerge from Georg Brandl <georg@python.org> parents: 65116 diff changeset	987 \| :const:`PyTrace_C_CALL` \| Function object being called. \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	988 +------------------------------+--------------------------------------+
66470 45e49269e0d8 Merged revisions 85530,85532-85534,85538-85543,85546-85548 via svnmerge from Georg Brandl <georg@python.org> parents: 65116 diff changeset	989 \| :const:`PyTrace_C_EXCEPTION` \| Function object being called. \|
45e49269e0d8 Merged revisions 85530,85532-85534,85538-85543,85546-85548 via svnmerge from Georg Brandl <georg@python.org> parents: 65116 diff changeset	990 +------------------------------+--------------------------------------+
45e49269e0d8 Merged revisions 85530,85532-85534,85538-85543,85546-85548 via svnmerge from Georg Brandl <georg@python.org> parents: 65116 diff changeset	991 \| :const:`PyTrace_C_RETURN` \| Function object being called. \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	992 +------------------------------+--------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	993
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	994
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	995 .. c:var:: int PyTrace_CALL
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	996
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	997 The value of the what parameter to a :c:type:`Py_tracefunc` function when a new
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	998 call to a function or method is being reported, or a new entry into a generator.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	999 Note that the creation of the iterator for a generator function is not reported
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1000 as there is no control transfer to the Python bytecode in the corresponding
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1001 frame.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1002
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1003
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	1004 .. c:var:: int PyTrace_EXCEPTION
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1005
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	1006 The value of the what parameter to a :c:type:`Py_tracefunc` function when an
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1007 exception has been raised. The callback function is called with this value for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1008 what when after any bytecode is processed after which the exception becomes
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1009 set within the frame being executed. The effect of this is that as exception
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1010 propagation causes the Python stack to unwind, the callback is called upon
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1011 return to each frame as the exception propagates. Only trace functions receives
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1012 these events; they are not needed by the profiler.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1013
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1014
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	1015 .. c:var:: int PyTrace_LINE
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1016
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1017 The value passed as the what parameter to a trace function (but not a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1018 profiling function) when a line-number event is being reported.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1019
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1020
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	1021 .. c:var:: int PyTrace_RETURN
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1022
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	1023 The value for the what parameter to :c:type:`Py_tracefunc` functions when a
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1024 call is returning without propagating an exception.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1025
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1026
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	1027 .. c:var:: int PyTrace_C_CALL
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1028
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	1029 The value for the what parameter to :c:type:`Py_tracefunc` functions when a C
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1030 function is about to be called.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1031
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1032
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	1033 .. c:var:: int PyTrace_C_EXCEPTION
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1034
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	1035 The value for the what parameter to :c:type:`Py_tracefunc` functions when a C
65116 90e1735df4d9 Merged revisions 83561,83563,83565-83566,83569,83571,83574-83575,83580,83584,83599,83612,83659,83977,84015-84018,84020,84141 via svnmerge from Georg Brandl <georg@python.org> parents: 65108 diff changeset	1036 function has raised an exception.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1037
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1038
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	1039 .. c:var:: int PyTrace_C_RETURN
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1040
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	1041 The value for the what parameter to :c:type:`Py_tracefunc` functions when a C
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1042 function has returned.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1043
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1044
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	1045 .. c:function:: void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1046
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1047 Set the profiler function to func. The obj parameter is passed to the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1048 function as its first parameter, and may be any Python object, or NULL. If
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1049 the profile function needs to maintain state, using a different value for obj
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1050 for each thread provides a convenient and thread-safe place to store it. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1051 profile function is called for all monitored events except the line-number
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1052 events.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1053
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1054
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	1055 .. c:function:: void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1056
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1057 Set the tracing function to func. This is similar to
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	1058 :c:func:`PyEval_SetProfile`, except the tracing function does receive line-number
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1059 events.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1060
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	1061 .. c:function:: PyObject* PyEval_GetCallStats(PyObject *self)
44104 ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1062
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1063 Return a tuple of function call counts. There are constants defined for the
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1064 positions within the tuple:
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49493 diff changeset	1065
44104 ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1066 +-------------------------------+-------+
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1067 \| Name \| Value \|
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1068 +===============================+=======+
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1069 \| :const:`PCALL_ALL` \| 0 \|
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1070 +-------------------------------+-------+
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1071 \| :const:`PCALL_FUNCTION` \| 1 \|
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1072 +-------------------------------+-------+
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1073 \| :const:`PCALL_FAST_FUNCTION` \| 2 \|
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1074 +-------------------------------+-------+
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1075 \| :const:`PCALL_FASTER_FUNCTION`\| 3 \|
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1076 +-------------------------------+-------+
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1077 \| :const:`PCALL_METHOD` \| 4 \|
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1078 +-------------------------------+-------+
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1079 \| :const:`PCALL_BOUND_METHOD` \| 5 \|
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1080 +-------------------------------+-------+
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1081 \| :const:`PCALL_CFUNCTION` \| 6 \|
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1082 +-------------------------------+-------+
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1083 \| :const:`PCALL_TYPE` \| 7 \|
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1084 +-------------------------------+-------+
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1085 \| :const:`PCALL_GENERATOR` \| 8 \|
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1086 +-------------------------------+-------+
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1087 \| :const:`PCALL_OTHER` \| 9 \|
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1088 +-------------------------------+-------+
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1089 \| :const:`PCALL_POP` \| 10 \|
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1090 +-------------------------------+-------+
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49493 diff changeset	1091
44104 ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1092 :const:`PCALL_FAST_FUNCTION` means no argument tuple needs to be created.
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1093 :const:`PCALL_FASTER_FUNCTION` means that the fast-path frame setup code is used.
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1094
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1095 If there is a method call where the call can be optimized by changing
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1096 the argument tuple and calling the function directly, it gets recorded
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1097 twice.
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1098
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1099 This function is only present if Python is compiled with :const:`CALL_PROFILE`
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	1100 defined.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1101
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1102 .. _advanced-debugging:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1103
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1104 Advanced Debugger Support
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1105 =========================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1106
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1107 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1108
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1109
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1110 These functions are only intended to be used by advanced debugging tools.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1111
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1112
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	1113 .. c:function:: PyInterpreterState* PyInterpreterState_Head()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1114
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1115 Return the interpreter state object at the head of the list of all such objects.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1116
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1117
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	1118 .. c:function:: PyInterpreterState* PyInterpreterState_Next(PyInterpreterState *interp)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1119
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1120 Return the next interpreter state object after interp from the list of all
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1121 such objects.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1122
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1123
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	1124 .. c:function:: PyThreadState * PyInterpreterState_ThreadHead(PyInterpreterState *interp)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1125
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	1126 Return the a pointer to the first :c:type:`PyThreadState` object in the list of
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1127 threads associated with the interpreter interp.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1128
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1129
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	1130 .. c:function:: PyThreadState* PyThreadState_Next(PyThreadState *tstate)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1131
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1132 Return the next thread state object after tstate from the list of all such
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64955 diff changeset	1133 objects belonging to the same :c:type:`PyInterpreterState` object.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1134

Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/init.rst @ 78069:a8aa77458e12 3.2