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

annotate Doc/c-api/init.rst @ 79675:c0a2294de787 2.7

Issue #16199: Backport 2to3 typo fix from 3.2.

author	Chris Jerdonek <chris.jerdonek@gmail.com>
date	Thu, 11 Oct 2012 16:15:46 -0700
parents	74ff71b2f53d
children	cedd1c94c534

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
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	11 Initializing and finalizing the interpreter
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	12 ===========================================
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	13
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	14
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 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: PyEval_ReleaseLock()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 single: PyEval_AcquireLock()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22 single: modules (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23 single: path (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 module: __builtin__
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 module: __main__
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26 module: sys
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27 triple: module; search; path
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 single: PySys_SetArgv()
61789 3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	29 single: PySys_SetArgvEx()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30 single: Py_Finalize()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32 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	33 should be called before using any other Python/C API functions; with the
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	34 exception of :c:func:`Py_SetProgramName`, :c:func:`Py_SetPythonHome`, :c:func:`PyEval_InitThreads`,
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	35 :c:func:`PyEval_ReleaseLock`, and :c:func:`PyEval_AcquireLock`. This initializes
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36 the table of loaded modules (``sys.modules``), and creates the fundamental
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37 modules :mod:`__builtin__`, :mod:`__main__` and :mod:`sys`. It also initializes
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38 the module search path (``sys.path``). It does not set ``sys.argv``; use
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	39 :c:func:`PySys_SetArgvEx` for that. This is a no-op when called for a second time
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	40 (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	41 fatal error if the initialization fails.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	44 .. 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	45
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	46 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	47 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	48 might be useful when Python is embedded.
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 .. versionadded:: 2.4
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	53 .. c:function:: int Py_IsInitialized()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55 Return true (nonzero) when the Python interpreter has been initialized, false
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	56 (zero) if not. After :c:func:`Py_Finalize` is called, this returns false until
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	57 :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	58
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	60 .. c:function:: void Py_Finalize()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	62 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	63 Python/C API functions, and destroy all sub-interpreters (see
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	64 :c:func:`Py_NewInterpreter` below) that were created and not yet destroyed since
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	65 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	66 allocated by the Python interpreter. This is a no-op when called for a second
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	67 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	68 value; errors during finalization are ignored.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 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	71 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	72 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	73 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	74 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	75 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	76 the application.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78 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	79 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	80 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	81 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	82 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	83 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	84 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	85 extensions may not work properly if their initialization routine is called more
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	86 than once; this can happen if an application calls :c:func:`Py_Initialize` and
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	87 :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	88
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	90 Process-wide parameters
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	91 =======================
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	94 .. c:function:: void Py_SetProgramName(char *name)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97 single: Py_Initialize()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98 single: main()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99 single: Py_GetPath()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	100
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	101 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	102 the first time, if it is called at all. It tells the interpreter the value
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	103 of the ``argv[0]`` argument to the :c:func:`main` function of the program.
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	104 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	105 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	106 default value is ``'python'``. The argument should point to a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107 zero-terminated character string in static storage whose contents will not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108 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	109 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	110
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	112 .. c:function:: char* Py_GetProgramName()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114 .. index:: single: Py_SetProgramName()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	116 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	117 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	118 value.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	121 .. c:function:: char* Py_GetPrefix()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123 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	124 through a number of complicated rules from the program name set with
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	125 :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	126 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	127 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	128 value. This corresponds to the :makevar:`prefix` variable in the top-level
72197 af04764ed7e4 Fix some markup and one typo Éric Araujo <merwok@netwok.org> parents: 71788 diff changeset	129 :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	130 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	131 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	132
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	134 .. c:function:: char* Py_GetExecPrefix()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136 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	137 derived through a number of complicated rules from the program name set with
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	138 :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	139 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	140 ``'/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	141 should not modify its value. This corresponds to the :makevar:`exec_prefix`
72197 af04764ed7e4 Fix some markup and one typo Éric Araujo <merwok@netwok.org> parents: 71788 diff changeset	142 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	143 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	144 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	145
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146 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	147 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	148 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	149 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	150 be installed in :file:`/usr/local`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 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	153 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	154 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	155 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	156 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	157 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	158 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	159 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	160 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	161 which they were compiled!).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163 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	164 :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	165 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	166 platform.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	169 .. c:function:: char* Py_GetProgramFullPath()
42604 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 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	172 single: Py_SetProgramName()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	173 single: executable (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	174
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	175 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	176 side-effect of deriving the default module search path from the program name
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	177 (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	178 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	179 to Python code as ``sys.executable``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	180
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	181
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	182 .. c:function:: char* Py_GetPath()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	183
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185 triple: module; search; path
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186 single: path (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 59831 diff changeset	188 Return the default module search path; this is computed from the program name
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	189 (set by :c:func:`Py_SetProgramName` above) and some environment variables.
59834 9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 59831 diff changeset	190 The returned string consists of a series of directory names separated by a
9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 59831 diff changeset	191 platform dependent delimiter character. The delimiter character is ``':'``
9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 59831 diff changeset	192 on Unix and Mac OS X, ``';'`` on Windows. The returned string points into
9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 59831 diff changeset	193 static storage; the caller should not modify its value. The list
9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 59831 diff changeset	194 :data:`sys.path` is initialized with this value on interpreter startup; it
9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 59831 diff changeset	195 can be (and usually is) modified later to change the search path for loading
9eabba6ded09 Merged revisions 77120,77151,77155,77209,77229,77256,77317,77331,77333,77359-77360,77382,77561,77570 via svnmerge from Georg Brandl <georg@python.org> parents: 59831 diff changeset	196 modules.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44110 diff changeset	198 .. XXX should give the exact rules
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	201 .. c:function:: const char* Py_GetVersion()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203 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	204 something like ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206 "1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	207
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208 .. index:: single: version (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210 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	211 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	212 period. The returned string points into static storage; the caller should not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213 modify its value. The value is available to Python code as ``sys.version``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	216 .. c:function:: const char* Py_GetPlatform()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 .. index:: single: platform (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	220 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	221 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	222 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	223 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	224 ``'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	225 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	226 to Python code as ``sys.platform``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	229 .. c:function:: const char* Py_GetCopyright()
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 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	232
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233 ``'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235 .. index:: single: copyright (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237 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	238 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	239
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	241 .. c:function:: const char* Py_GetCompiler()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243 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	244 in square brackets, for example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246 "[GCC 2.7.2.2]"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248 .. index:: single: version (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250 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	251 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	252 ``sys.version``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	254
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	255 .. c:function:: const char* Py_GetBuildInfo()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	256
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	257 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	258 current Python interpreter instance, for example ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260 "#67, Aug 1 1997, 22:34:28"
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 .. index:: single: version (in module sys)
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 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	265 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	266 ``sys.version``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	267
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	268
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	269 .. c:function:: void PySys_SetArgvEx(int argc, char **argv, int updatepath)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	270
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	271 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	272 single: main()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273 single: Py_FatalError()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	274 single: argv (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	275
51809 a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	276 Set :data:`sys.argv` based on argc and argv. These parameters are
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	277 similar to those passed to the program's :c:func:`main` function with the
51809 a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	278 difference that the first entry should refer to the script file to be
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	279 executed rather than the executable hosting the Python interpreter. If there
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	280 isn't a script that will be run, the first entry in argv can be an empty
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	281 string. If this function fails to initialize :data:`sys.argv`, a fatal
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	282 condition is signalled using :c:func:`Py_FatalError`.
51809 a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	283
61789 3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	284 If updatepath is zero, this is all the function does. If updatepath
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	285 is non-zero, the function also modifies :data:`sys.path` according to the
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	286 following algorithm:
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	287
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	288 - If the name of an existing script is passed in ``argv[0]``, the absolute
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	289 path of the directory where the script is located is prepended to
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	290 :data:`sys.path`.
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	291 - Otherwise (that is, if argc is 0 or ``argv[0]`` doesn't point
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	292 to an existing file name), an empty string is prepended to
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	293 :data:`sys.path`, which is the same as prepending the current working
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	294 directory (``"."``).
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	295
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	296 .. note::
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	297 It is recommended that applications embedding the Python interpreter
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	298 for purposes other than executing a single script pass 0 as updatepath,
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	299 and update :data:`sys.path` themselves if desired.
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	300 See `CVE-2008-5983 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983>`_.
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	301
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	302 On versions before 2.6.6, you can achieve the same effect by manually
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	303 popping the first :data:`sys.path` element after having called
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	304 :c:func:`PySys_SetArgv`, for example using::
61789 3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	305
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	306 PyRun_SimpleString("import sys; sys.path.pop(0)\n");
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	307
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	308 .. versionadded:: 2.6.6
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	309
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44110 diff changeset	310 .. XXX impl. doesn't seem consistent in allowing 0/NULL for the params;
3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44110 diff changeset	311 check w/ Guido.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	314 .. c:function:: void PySys_SetArgv(int argc, char **argv)
61789 3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	315
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	316 This function works like :c:func:`PySys_SetArgvEx` with updatepath set to 1.
61789 3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	317
3f08d98c8fa5 Merged revisions 81398 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 59834 diff changeset	318
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	319 .. c:function:: void Py_SetPythonHome(char *home)
51809 a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	320
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	321 Set the default "home" directory, that is, the location of the standard
68014 d356649504f9 Merged revisions 86881,86887,86913-86915,86933,86943,86960,86964,86974,86980,86996,87008 via svnmerge from Georg Brandl <georg@python.org> parents: 67612 diff changeset	322 Python libraries. See :envvar:`PYTHONHOME` for the meaning of the
d356649504f9 Merged revisions 86881,86887,86913-86915,86933,86943,86960,86964,86974,86980,86996,87008 via svnmerge from Georg Brandl <georg@python.org> parents: 67612 diff changeset	323 argument string.
d356649504f9 Merged revisions 86881,86887,86913-86915,86933,86943,86960,86964,86974,86980,86996,87008 via svnmerge from Georg Brandl <georg@python.org> parents: 67612 diff changeset	324
55963 4ab3b5eae897 Merged revisions 74795 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 53588 diff changeset	325 The argument should point to a zero-terminated character string in static
4ab3b5eae897 Merged revisions 74795 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 53588 diff changeset	326 storage whose contents will not change for the duration of the program's
4ab3b5eae897 Merged revisions 74795 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 53588 diff changeset	327 execution. No code in the Python interpreter will change the contents of
4ab3b5eae897 Merged revisions 74795 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 53588 diff changeset	328 this storage.
51809 a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	329
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	330
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	331 .. c:function:: char* Py_GetPythonHome()
51809 a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	332
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	333 Return the default "home", that is, the value set by a previous call to
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	334 :c:func:`Py_SetPythonHome`, or the value of the :envvar:`PYTHONHOME`
51809 a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	335 environment variable if it is set.
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	336
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	337
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	338 .. _threads:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	339
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340 Thread State and the Global Interpreter Lock
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	341 ============================================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	343 .. index::
65376 eec499847df7 #10111: minor problems in 2.7 FILE* API docs. Georg Brandl <georg@python.org> parents: 65127 diff changeset	344 single: GIL
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345 single: global interpreter lock
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	346 single: interpreter lock
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	347 single: lock, interpreter
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348
66459 37b37b6a8972 Merged revisions 85731,85735 via svnmerge from Georg Brandl <georg@python.org> parents: 66453 diff changeset	349 The Python interpreter is not fully thread-safe. In order to support
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	350 multi-threaded Python programs, there's a global lock, called the :term:`global
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	351 interpreter lock` or :term:`GIL`, that must be held by the current thread before
52903 3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	352 it can safely access Python objects. Without the lock, even the simplest
3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	353 operations could cause problems in a multi-threaded program: for example, when
3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	354 two threads simultaneously increment the reference count of the same object, the
3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	355 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	356
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357 .. index:: single: setcheckinterval() (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	359 Therefore, the rule exists that only the thread that has acquired the
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	360 :term:`GIL` may operate on Python objects or call Python/C API functions.
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	361 In order to emulate concurrency of execution, the interpreter regularly
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	362 tries to switch threads (see :func:`sys.setcheckinterval`). The lock is also
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	363 released around potentially blocking I/O operations like reading or writing
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	364 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	365
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	366 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	367 single: PyThreadState
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	368 single: PyThreadState
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	369
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	370 The Python interpreter keeps some thread-specific bookkeeping information
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	371 inside a data structure called :c:type:`PyThreadState`. There's also one
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	372 global variable pointing to the current :c:type:`PyThreadState`: it can
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	373 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	374
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	375 Releasing the GIL from extension code
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	376 -------------------------------------
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	377
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	378 Most extension code manipulating the :term:`GIL` has the following simple
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	379 structure::
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 Save the thread state in a local variable.
52903 3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	382 Release the global interpreter lock.
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	383 ... Do some blocking I/O operation ...
52903 3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	384 Reacquire the global interpreter lock.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	385 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	386
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	387 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	388
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	389 Py_BEGIN_ALLOW_THREADS
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	390 ... Do some blocking I/O operation ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391 Py_END_ALLOW_THREADS
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	392
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	393 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	394 single: Py_BEGIN_ALLOW_THREADS
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	395 single: Py_END_ALLOW_THREADS
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	397 The :c:macro:`Py_BEGIN_ALLOW_THREADS` macro opens a new block and declares a
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	398 hidden local variable; the :c:macro:`Py_END_ALLOW_THREADS` macro closes the
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	399 block. These two macros are still available when Python is compiled without
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	400 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	401
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	402 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	403
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	404 PyThreadState *_save;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	405
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	406 _save = PyEval_SaveThread();
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	407 ...Do some blocking I/O operation...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408 PyEval_RestoreThread(_save);
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	409
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	410 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411 single: PyEval_RestoreThread()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	412 single: PyEval_SaveThread()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	413
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	414 Here is how these functions work: the global interpreter lock is used to protect the pointer to the
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	415 current thread state. When releasing the lock and saving the thread state,
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	416 the current thread state pointer must be retrieved before the lock is released
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	417 (since another thread could immediately acquire the lock and store its own thread
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	418 state in the global variable). Conversely, when acquiring the lock and restoring
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	419 the thread state, the lock must be acquired before storing the thread state
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	420 pointer.
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	421
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	422 .. note::
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	423 Calling system I/O functions is the most common use case for releasing
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	424 the GIL, but it can also be useful before calling long-running computations
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	425 which don't need access to Python objects, such as compression or
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	426 cryptographic functions operating over memory buffers. For example, the
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	427 standard :mod:`zlib` and :mod:`hashlib` modules release the GIL when
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	428 compressing or hashing data.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	429
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	430 Non-Python created threads
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	431 --------------------------
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	432
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	433 When threads are created using the dedicated Python APIs (such as the
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	434 :mod:`threading` module), a thread state is automatically associated to them
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	435 and the code showed above is therefore correct. However, when threads are
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	436 created from C (for example by a third-party library with its own thread
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	437 management), they don't hold the GIL, nor is there a thread state structure
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	438 for them.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	439
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	440 If you need to call Python code from these threads (often this will be part
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	441 of a callback API provided by the aforementioned third-party library),
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	442 you must first register these threads with the interpreter by
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	443 creating a thread state data structure, then acquiring the GIL, and finally
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	444 storing their thread state pointer, before you can start using the Python/C
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	445 API. When you are done, you should reset the thread state pointer, release
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	446 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	447
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	448 The :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` functions do
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	449 all of the above automatically. The typical idiom for calling into Python
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	450 from a C thread is::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	451
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	452 PyGILState_STATE gstate;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	453 gstate = PyGILState_Ensure();
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	454
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	455 /* Perform Python actions here. */
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	456 result = CallSomeFunction();
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	457 /* evaluate result or handle exception */
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	458
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	459 /* 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	460 PyGILState_Release(gstate);
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	461
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	462 Note that the :c:func:`PyGILState_\*` functions assume there is only one global
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	463 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	464 supports the creation of additional interpreters (using
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	465 :c:func:`Py_NewInterpreter`), but mixing multiple interpreters and the
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	466 :c:func:`PyGILState_\*` API is unsupported.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	467
56008 1ad9f2bda20a Merged revisions 74841 via svnmerge from Thomas Wouters <thomas@python.org> parents: 55963 diff changeset	468 Another important thing to note about threads is their behaviour in the face
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	469 of the C :c:func:`fork` call. On most systems with :c:func:`fork`, after a
56008 1ad9f2bda20a Merged revisions 74841 via svnmerge from Thomas Wouters <thomas@python.org> parents: 55963 diff changeset	470 process forks only the thread that issued the fork will exist. That also
1ad9f2bda20a Merged revisions 74841 via svnmerge from Thomas Wouters <thomas@python.org> parents: 55963 diff changeset	471 means any locks held by other threads will never be released. Python solves
1ad9f2bda20a Merged revisions 74841 via svnmerge from Thomas Wouters <thomas@python.org> parents: 55963 diff changeset	472 this for :func:`os.fork` by acquiring the locks it uses internally before
1ad9f2bda20a Merged revisions 74841 via svnmerge from Thomas Wouters <thomas@python.org> parents: 55963 diff changeset	473 the fork, and releasing them afterwards. In addition, it resets any
1ad9f2bda20a Merged revisions 74841 via svnmerge from Thomas Wouters <thomas@python.org> parents: 55963 diff changeset	474 :ref:`lock-objects` in the child. When extending or embedding Python, there
1ad9f2bda20a Merged revisions 74841 via svnmerge from Thomas Wouters <thomas@python.org> parents: 55963 diff changeset	475 is no way to inform Python of additional (non-Python) locks that need to be
1ad9f2bda20a Merged revisions 74841 via svnmerge from Thomas Wouters <thomas@python.org> parents: 55963 diff changeset	476 acquired before or reset after a fork. OS facilities such as
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	477 :c:func:`pthread_atfork` would need to be used to accomplish the same thing.
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	478 Additionally, when extending or embedding Python, calling :c:func:`fork`
56008 1ad9f2bda20a Merged revisions 74841 via svnmerge from Thomas Wouters <thomas@python.org> parents: 55963 diff changeset	479 directly rather than through :func:`os.fork` (and returning to or calling
1ad9f2bda20a Merged revisions 74841 via svnmerge from Thomas Wouters <thomas@python.org> parents: 55963 diff changeset	480 into Python) may result in a deadlock by one of Python's internal locks
1ad9f2bda20a Merged revisions 74841 via svnmerge from Thomas Wouters <thomas@python.org> parents: 55963 diff changeset	481 being held by a thread that is defunct after the fork.
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	482 :c:func:`PyOS_AfterFork` tries to reset the necessary locks, but is not
56008 1ad9f2bda20a Merged revisions 74841 via svnmerge from Thomas Wouters <thomas@python.org> parents: 55963 diff changeset	483 always able to.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	484
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	485
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	486 High-level API
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	487 --------------
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	488
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	489 These are the most commonly used types and functions when writing C extension
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	490 code, or when embedding the Python interpreter:
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	491
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	492 .. c:type:: PyInterpreterState
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	493
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	494 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	495 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	496 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	497 this structure.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	498
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499 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	500 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	501 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	502 interpreter they belong.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	503
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	504
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	505 .. c:type:: PyThreadState
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	506
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	507 This data structure represents the state of a single thread. The only public
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	508 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	509 this thread's interpreter state.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	510
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	511
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	512 .. c:function:: void PyEval_InitThreads()
42604 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 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	515 single: PyEval_ReleaseLock()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	516 single: PyEval_ReleaseThread()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	517 single: PyEval_SaveThread()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	518 single: PyEval_RestoreThread()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	519
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	520 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	521 main thread before creating a second thread or engaging in any other thread
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	522 operations such as :c:func:`PyEval_ReleaseLock` or
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	523 ``PyEval_ReleaseThread(tstate)``. It is not needed before calling
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	524 :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	525
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	526 .. index:: single: Py_Initialize()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	527
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	528 This is a no-op when called for a second time. It is safe to call this function
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	529 before calling :c:func:`Py_Initialize`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	530
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	531 .. index:: module: thread
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	532
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	533 .. note::
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	534 When only the main thread exists, no GIL operations are needed. This is a
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	535 common situation (most Python programs do not use threads), and the lock
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	536 operations slow the interpreter down a bit. Therefore, the lock is not
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	537 created initially. This situation is equivalent to having acquired the lock:
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	538 when there is only a single thread, all object accesses are safe. Therefore,
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	539 when this function initializes the global interpreter lock, it also acquires
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	540 it. Before the Python :mod:`_thread` module creates a new thread, knowing
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	541 that either it has the lock or the lock hasn't been created yet, it calls
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	542 :c:func:`PyEval_InitThreads`. When this call returns, it is guaranteed that
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	543 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	544
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	545 It is not safe to call this function when it is unknown which thread (if
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	546 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	547
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	548 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	549
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	550
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	551 .. c:function:: int PyEval_ThreadsInitialized()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	552
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	553 Returns a non-zero value if :c:func:`PyEval_InitThreads` has been called. This
52903 3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	554 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	555 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	556 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	557
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	558 .. versionadded:: 2.4
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	559
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	560
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	561 .. c:function:: PyThreadState* PyEval_SaveThread()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	562
52903 3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	563 Release the global interpreter lock (if it has been created and thread
3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	564 support is enabled) and reset the thread state to NULL, returning the
3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	565 previous thread state (which is not NULL). If the lock has been created,
3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	566 the current thread must have acquired it. (This function is available even
3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	567 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	568
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	569
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	570 .. 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	571
52903 3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	572 Acquire the global interpreter lock (if it has been created and thread
3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	573 support is enabled) and set the thread state to tstate, which must not be
3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	574 NULL. If the lock has been created, the current thread must not have
3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	575 acquired it, otherwise deadlock ensues. (This function is available even
3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	576 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	577
44093 4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	578
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	579 .. c:function:: PyThreadState* PyThreadState_Get()
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	580
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	581 Return the current thread state. The global interpreter lock must be held.
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	582 When the current thread state is NULL, this issues a fatal error (so that
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	583 the caller needn't check for NULL).
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	584
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	585
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	586 .. c:function:: PyThreadState* PyThreadState_Swap(PyThreadState *tstate)
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	587
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	588 Swap the current thread state with the thread state given by the argument
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	589 tstate, which may be NULL. The global interpreter lock must be held
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	590 and is not released.
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	591
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	592
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	593 .. c:function:: void PyEval_ReInitThreads()
44093 4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	594
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	595 This function is called from :c:func:`PyOS_AfterFork` to ensure that newly
44093 4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	596 created child processes don't hold locks referring to threads which
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	597 are not running in the child process.
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	598
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	599
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	600 The following functions use thread-local storage, and are not compatible
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	601 with sub-interpreters:
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	602
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	603 .. c:function:: PyGILState_STATE PyGILState_Ensure()
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	604
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	605 Ensure that the current thread is ready to call the Python C API regardless
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	606 of the current state of Python, or of the global interpreter lock. This may
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	607 be called as many times as desired by a thread as long as each call is
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	608 matched with a call to :c:func:`PyGILState_Release`. In general, other
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	609 thread-related APIs may be used between :c:func:`PyGILState_Ensure` and
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	610 :c:func:`PyGILState_Release` calls as long as the thread state is restored to
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	611 its previous state before the Release(). For example, normal usage of the
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	612 :c:macro:`Py_BEGIN_ALLOW_THREADS` and :c:macro:`Py_END_ALLOW_THREADS` macros is
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	613 acceptable.
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	614
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	615 The return value is an opaque "handle" to the thread state when
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	616 :c:func:`PyGILState_Ensure` was called, and must be passed to
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	617 :c:func:`PyGILState_Release` to ensure Python is left in the same state. Even
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	618 though recursive calls are allowed, these handles cannot be shared - each
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	619 unique call to :c:func:`PyGILState_Ensure` must save the handle for its call
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	620 to :c:func:`PyGILState_Release`.
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	621
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	622 When the function returns, the current thread will hold the GIL and be able
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	623 to call arbitrary Python code. Failure is a fatal error.
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	624
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	625 .. versionadded:: 2.3
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	626
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	627
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	628 .. c:function:: void PyGILState_Release(PyGILState_STATE)
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	629
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	630 Release any resources previously acquired. After this call, Python's state will
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	631 be the same as it was prior to the corresponding :c:func:`PyGILState_Ensure` call
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	632 (but generally this state will be unknown to the caller, hence the use of the
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	633 GILState API).
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	634
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	635 Every call to :c:func:`PyGILState_Ensure` must be matched by a call to
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	636 :c:func:`PyGILState_Release` on the same thread.
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	637
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	638 .. versionadded:: 2.3
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	639
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	640
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	641 .. c:function:: PyThreadState PyGILState_GetThisThreadState()
71768 8852e4a9aa1e #10741: add documentation for PyGILState_GetThisThreadState() Sandro Tosi <sandro.tosi@gmail.com> parents: 69842 diff changeset	642
8852e4a9aa1e #10741: add documentation for PyGILState_GetThisThreadState() Sandro Tosi <sandro.tosi@gmail.com> parents: 69842 diff changeset	643 Get the current thread state for this thread. May return ``NULL`` if no
8852e4a9aa1e #10741: add documentation for PyGILState_GetThisThreadState() Sandro Tosi <sandro.tosi@gmail.com> parents: 69842 diff changeset	644 GILState API has been used on the current thread. Note that the main thread
8852e4a9aa1e #10741: add documentation for PyGILState_GetThisThreadState() Sandro Tosi <sandro.tosi@gmail.com> parents: 69842 diff changeset	645 always has such a thread-state, even if no auto-thread-state call has been
8852e4a9aa1e #10741: add documentation for PyGILState_GetThisThreadState() Sandro Tosi <sandro.tosi@gmail.com> parents: 69842 diff changeset	646 made on the main thread. This is mainly a helper/diagnostic function.
8852e4a9aa1e #10741: add documentation for PyGILState_GetThisThreadState() Sandro Tosi <sandro.tosi@gmail.com> parents: 69842 diff changeset	647
8852e4a9aa1e #10741: add documentation for PyGILState_GetThisThreadState() Sandro Tosi <sandro.tosi@gmail.com> parents: 69842 diff changeset	648 .. versionadded:: 2.3
8852e4a9aa1e #10741: add documentation for PyGILState_GetThisThreadState() Sandro Tosi <sandro.tosi@gmail.com> parents: 69842 diff changeset	649
8852e4a9aa1e #10741: add documentation for PyGILState_GetThisThreadState() Sandro Tosi <sandro.tosi@gmail.com> parents: 69842 diff changeset	650
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	651 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	652 example usage in the Python source distribution.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	653
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	654
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	655 .. c:macro:: Py_BEGIN_ALLOW_THREADS
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	656
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	657 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	658 Note that it contains an opening brace; it must be matched with a following
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	659 :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	660 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	661
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	662
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	663 .. c:macro:: Py_END_ALLOW_THREADS
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	664
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	665 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	666 a closing brace; it must be matched with an earlier
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	667 :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	668 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	669
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	670
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	671 .. c:macro:: Py_BLOCK_THREADS
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	672
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	673 This macro expands to ``PyEval_RestoreThread(_save);``: it is equivalent to
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	674 :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	675 thread support is disabled at compile time.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	676
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	677
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	678 .. c:macro:: Py_UNBLOCK_THREADS
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	679
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	680 This macro expands to ``_save = PyEval_SaveThread();``: it is equivalent to
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	681 :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	682 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	683
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	684
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	685 Low-level API
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	686 -------------
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	687
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	688 All of the following functions are only available when thread support is enabled
52903 3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	689 at compile time, and must be called only when the global interpreter lock has
3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	690 been created.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	691
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	692
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	693 .. c:function:: PyInterpreterState* PyInterpreterState_New()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	694
52903 3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	695 Create a new interpreter state object. The global interpreter lock need not
3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	696 be held, but may be held if it is necessary to serialize calls to this
3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	697 function.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	698
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	699
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	700 .. 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	701
52903 3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	702 Reset all information in an interpreter state object. The global interpreter
3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	703 lock must be held.
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
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	706 .. 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	707
52903 3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	708 Destroy an interpreter state object. The global interpreter lock need not be
3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	709 held. The interpreter state must have been reset with a previous call to
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	710 :c:func:`PyInterpreterState_Clear`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	711
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	712
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	713 .. 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	714
52903 3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	715 Create a new thread state object belonging to the given interpreter object.
3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	716 The global interpreter lock need not be held, but may be held if it is
3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	717 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	718
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	719
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	720 .. 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	721
52903 3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	722 Reset all information in a thread state object. The global interpreter lock
3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	723 must be held.
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
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	726 .. 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	727
52903 3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	728 Destroy a thread state object. The global interpreter lock need not be held.
3889d9528601 Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	729 The thread state must have been reset with a previous call to
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	730 :c:func:`PyThreadState_Clear`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	731
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	732
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	733 .. c:function:: PyObject* PyThreadState_GetDict()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	734
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	735 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	736 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	737 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	738 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	739 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	740
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	741 .. versionchanged:: 2.3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	742 Previously this could only be called when a current thread is active, and NULL
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	743 meant that an exception was raised.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	744
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	745
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	746 .. 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	747
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	748 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	749 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	750 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	751 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	752 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	753 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	754 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	755
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	756 .. versionadded:: 2.3
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
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	759 .. c:function:: void PyEval_AcquireThread(PyThreadState *tstate)
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	760
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	761 Acquire the global interpreter lock and set the current thread state to
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	762 tstate, which should not be NULL. The lock must have been created earlier.
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	763 If this thread already has the lock, deadlock ensues.
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	764
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	765 :c:func:`PyEval_RestoreThread` is a higher-level function which is always
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	766 available (even when thread support isn't enabled or when threads have
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	767 not been initialized).
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	768
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	769
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	770 .. c:function:: void PyEval_ReleaseThread(PyThreadState *tstate)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	771
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	772 Reset the current thread state to NULL and release the global interpreter
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	773 lock. The lock must have been created earlier and must be held by the current
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	774 thread. The tstate argument, which must not be NULL, is only used to check
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	775 that it represents the current thread state --- if it isn't, a fatal error is
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	776 reported.
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	777
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	778 :c:func:`PyEval_SaveThread` is a higher-level function which is always
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	779 available (even when thread support isn't enabled or when threads have
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	780 not been initialized).
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	781
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	782
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 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
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	785 Acquire the global interpreter lock. The lock must have been created earlier.
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	786 If this thread already has the lock, a deadlock ensues.
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	787
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	788 .. warning::
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	789 This function does not change the current thread state. Please use
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	790 :c:func:`PyEval_RestoreThread` or :c:func:`PyEval_AcquireThread`
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	791 instead.
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	792
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	793
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	794 .. c:function:: void PyEval_ReleaseLock()
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	795
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 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
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	798 .. warning::
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	799 This function does not change the current thread state. Please use
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	800 :c:func:`PyEval_SaveThread` or :c:func:`PyEval_ReleaseThread`
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	801 instead.
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	802
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	803
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	804 Sub-interpreter support
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	805 =======================
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	806
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	807 While in most uses, you will only embed a single Python interpreter, there
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	808 are cases where you need to create several independent interpreters in the
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	809 same process and perhaps even in the same thread. Sub-interpreters allow
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	810 you to do that. You can switch between sub-interpreters using the
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	811 :c:func:`PyThreadState_Swap` function. You can create and destroy them
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 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
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	815 .. c:function:: PyThreadState* Py_NewInterpreter()
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	816
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	817 .. index::
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	818 module: builtins
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	819 module: __main__
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	820 module: sys
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	821 single: stdout (in module sys)
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	822 single: stderr (in module sys)
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	823 single: stdin (in module sys)
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	824
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	825 Create a new sub-interpreter. This is an (almost) totally separate environment
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	826 for the execution of Python code. In particular, the new interpreter has
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	827 separate, independent versions of all imported modules, including the
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	828 fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`. The
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	829 table of loaded modules (``sys.modules``) and the module search path
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	830 (``sys.path``) are also separate. The new environment has no ``sys.argv``
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	831 variable. It has new standard I/O stream file objects ``sys.stdin``,
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	832 ``sys.stdout`` and ``sys.stderr`` (however these refer to the same underlying
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	833 file descriptors).
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	834
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	835 The return value points to the first thread state created in the new
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	836 sub-interpreter. This thread state is made in the current thread state.
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	837 Note that no actual thread is created; see the discussion of thread states
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	838 below. If creation of the new interpreter is unsuccessful, NULL is
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	839 returned; no exception is set since the exception state is stored in the
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	840 current thread state and there may not be a current thread state. (Like all
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	841 other Python/C API functions, the global interpreter lock must be held before
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	842 calling this function and is still held when it returns; however, unlike most
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	843 other Python/C API functions, there needn't be a current thread state on
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	844 entry.)
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	845
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	846 .. index::
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	847 single: Py_Finalize()
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 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
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	850 Extension modules are shared between (sub-)interpreters as follows: the first
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	851 time a particular extension is imported, it is initialized normally, and a
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	852 (shallow) copy of its module's dictionary is squirreled away. When the same
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	853 extension is imported by another (sub-)interpreter, a new module is initialized
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	854 and filled with the contents of this copy; the extension's ``init`` function is
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	855 not called. Note that this is different from what happens when an extension is
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	856 imported after the interpreter has been completely re-initialized by calling
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	857 :c:func:`Py_Finalize` and :c:func:`Py_Initialize`; in that case, the extension's
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	858 ``initmodule`` function is called again.
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	859
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	860 .. index:: single: close() (in module os)
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	861
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	862
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	863 .. c:function:: void Py_EndInterpreter(PyThreadState *tstate)
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	864
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	865 .. index:: single: Py_Finalize()
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	866
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	867 Destroy the (sub-)interpreter represented by the given thread state. The given
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	868 thread state must be the current thread state. See the discussion of thread
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	869 states below. When the call returns, the current thread state is NULL. All
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	870 thread states associated with this interpreter are destroyed. (The global
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	871 interpreter lock must be held before calling this function and is still held
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	872 when it returns.) :c:func:`Py_Finalize` will destroy all sub-interpreters that
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	873 haven't been explicitly destroyed at that point.
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	874
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	875
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	876 Bugs and caveats
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	877 ----------------
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	878
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	879 Because sub-interpreters (and the main interpreter) are part of the same
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	880 process, the insulation between them isn't perfect --- for example, using
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	881 low-level file operations like :func:`os.close` they can
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	882 (accidentally or maliciously) affect each other's open files. Because of the
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	883 way extensions are shared between (sub-)interpreters, some extensions may not
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	884 work properly; this is especially likely when the extension makes use of
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	885 (static) global variables, or when the extension manipulates its module's
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	886 dictionary after its initialization. It is possible to insert objects created
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	887 in one sub-interpreter into a namespace of another sub-interpreter; this should
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	888 be done with great care to avoid sharing user-defined functions, methods,
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	889 instances or classes between sub-interpreters, since import operations executed
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	890 by such objects may affect the wrong (sub-)interpreter's dictionary of loaded
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	891 modules.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	892
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	893 Also note that combining this functionality with :c:func:`PyGILState_\*` APIs
69842 76a2354aa427 #11997: fix typo in init.rst. Ezio Melotti <ezio.melotti@gmail.com> parents: 69639 diff changeset	894 is delicate, because these APIs assume a bijection between Python thread states
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	895 and OS-level threads, an assumption broken by the presence of sub-interpreters.
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	896 It is highly recommended that you don't switch sub-interpreters between a pair
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	897 of matching :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` calls.
67612 ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	898 Furthermore, extensions (such as :mod:`ctypes`) using these APIs to allow calling
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	899 of Python code from non-Python created threads will probably be broken when using
ef0777af9978 Merged revisions 88012-88018 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66459 diff changeset	900 sub-interpreters.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	901
50675 e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	902
e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	903 Asynchronous Notifications
e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	904 ==========================
e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	905
52777 44954e6a1353 Fix 'the the' duplication Andrew M. Kuchling <amk@amk.ca> parents: 52143 diff changeset	906 A mechanism is provided to make asynchronous notifications to the main
50675 e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	907 interpreter thread. These notifications take the form of a function
e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	908 pointer and a void argument.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	909
50675 e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	910 .. index:: single: setcheckinterval() (in module sys)
e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	911
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	912 Every check interval, when the global interpreter lock is released and
57795 f7f5e1d27e06 #7388: "python".capitalize() in the Doc Ezio Melotti <ezio.melotti@gmail.com> parents: 57774 diff changeset	913 reacquired, Python will also call any such provided functions. This can be used
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	914 for example by asynchronous IO handlers. The notification can be scheduled from
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	915 a worker thread and the actual call than made at the earliest convenience by the
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	916 main thread where it has possession of the global interpreter lock and can
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	917 perform any Python API calls.
50675 e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	918
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	919 .. c:function:: int Py_AddPendingCall(int (func)(void ), void *arg)
50675 e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	920
e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	921 .. index:: single: Py_AddPendingCall()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	922
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	923 Post a notification to the Python main thread. If successful, func will be
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	924 called with the argument arg at the earliest convenience. func will be
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	925 called having the global interpreter lock held and can thus use the full
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	926 Python API and can take any action such as setting object attributes to
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	927 signal IO completion. It must return 0 on success, or -1 signalling an
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	928 exception. The notification function won't be interrupted to perform another
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	929 asynchronous notification recursively, but it can still be interrupted to
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	930 switch threads if the global interpreter lock is released, for example, if it
57795 f7f5e1d27e06 #7388: "python".capitalize() in the Doc Ezio Melotti <ezio.melotti@gmail.com> parents: 57774 diff changeset	931 calls back into Python code.
50675 e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	932
e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	933 This function returns 0 on success in which case the notification has been
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	934 scheduled. Otherwise, for example if the notification buffer is full, it
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	935 returns -1 without setting any exception.
50675 e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	936
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	937 This function can be called on any thread, be it a Python thread or some
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	938 other system thread. If it is a Python thread, it doesn't matter if it holds
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	939 the global interpreter lock or not.
50675 e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	940
e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	941 .. versionadded:: 2.7
e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	942
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	943
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	944
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	945 .. _profiling:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	946
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	947 Profiling and Tracing
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	950 .. 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	951
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	952
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	953 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	954 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	955 coverage analysis tools.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	956
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	957 Starting with Python 2.2, the implementation of this facility was substantially
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	958 revised, and an interface from C was added. This C interface allows the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	959 profiling or tracing code to avoid the overhead of calling through Python-level
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	960 callable objects, making a direct C function call instead. The essential
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	961 attributes of the facility have not changed; the interface allows trace
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	962 functions to be installed per-thread, and the basic events reported to the trace
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	963 function are the same as had been reported to the Python-level trace functions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	964 in previous versions.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	965
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	966
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	967 .. 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	968
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	969 The type of the trace function registered using :c:func:`PyEval_SetProfile` and
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	970 :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	971 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	972 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	973 :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	974 :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	975 :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	976
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	977 +------------------------------+--------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	978 \| Value of what \| Meaning of arg \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	979 +==============================+======================================+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	980 \| :const:`PyTrace_CALL` \| Always NULL. \|
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_EXCEPTION` \| Exception information as returned by \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	983 \| \| :func:`sys.exc_info`. \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	984 +------------------------------+--------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	985 \| :const:`PyTrace_LINE` \| Always NULL. \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	986 +------------------------------+--------------------------------------+
66453 8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from Georg Brandl <georg@python.org> parents: 65376 diff changeset	987 \| :const:`PyTrace_RETURN` \| Value being returned to the caller, \|
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from Georg Brandl <georg@python.org> parents: 65376 diff changeset	988 \| \| 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	989 +------------------------------+--------------------------------------+
66453 8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from Georg Brandl <georg@python.org> parents: 65376 diff changeset	990 \| :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	991 +------------------------------+--------------------------------------+
66453 8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from Georg Brandl <georg@python.org> parents: 65376 diff changeset	992 \| :const:`PyTrace_C_EXCEPTION` \| Function object being called. \|
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from Georg Brandl <georg@python.org> parents: 65376 diff changeset	993 +------------------------------+--------------------------------------+
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from Georg Brandl <georg@python.org> parents: 65376 diff changeset	994 \| :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	995 +------------------------------+--------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	996
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	997
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	998 .. c:var:: int PyTrace_CALL
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	999
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	1000 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	1001 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	1002 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	1003 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	1004 frame.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1005
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1006
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	1007 .. c:var:: int PyTrace_EXCEPTION
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1008
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	1009 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	1010 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	1011 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	1012 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	1013 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	1014 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	1015 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	1016
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1017
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	1018 .. c:var:: int PyTrace_LINE
42604 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 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	1021 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	1022
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1023
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	1024 .. c:var:: int PyTrace_RETURN
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1025
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	1026 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	1027 call is returning without propagating an exception.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1028
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1029
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	1030 .. c:var:: int PyTrace_C_CALL
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1031
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	1032 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	1033 function is about to be called.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1034
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1035
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	1036 .. c:var:: int PyTrace_C_EXCEPTION
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1037
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	1038 The value for the what parameter to :c:type:`Py_tracefunc` functions when a C
65127 ff734f225b47 Merged revisions 82798,82805,83659,83977,84015,84018,84141,84264,84326-84327,84480,84482,84484,84530-84531,84553,84619,84915-84916 via svnmerge from Georg Brandl <georg@python.org> parents: 62326 diff changeset	1039 function has raised an exception.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1040
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1041
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	1042 .. c:var:: int PyTrace_C_RETURN
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1043
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	1044 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	1045 function has returned.
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
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	1048 .. 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	1049
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1050 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	1051 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	1052 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	1053 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	1054 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	1055 events.
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
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	1058 .. 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	1059
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1060 Set the tracing function to func. This is similar to
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	1061 :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	1062 events.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1063
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	1064 .. c:function:: PyObject* PyEval_GetCallStats(PyObject *self)
44093 4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1065
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1066 Return a tuple of function call counts. There are constants defined for the
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1067 positions within the tuple:
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	1068
44093 4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1069 +-------------------------------+-------+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1070 \| Name \| Value \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1071 +===============================+=======+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1072 \| :const:`PCALL_ALL` \| 0 \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1073 +-------------------------------+-------+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1074 \| :const:`PCALL_FUNCTION` \| 1 \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1075 +-------------------------------+-------+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1076 \| :const:`PCALL_FAST_FUNCTION` \| 2 \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1077 +-------------------------------+-------+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1078 \| :const:`PCALL_FASTER_FUNCTION`\| 3 \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1079 +-------------------------------+-------+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1080 \| :const:`PCALL_METHOD` \| 4 \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1081 +-------------------------------+-------+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1082 \| :const:`PCALL_BOUND_METHOD` \| 5 \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1083 +-------------------------------+-------+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1084 \| :const:`PCALL_CFUNCTION` \| 6 \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1085 +-------------------------------+-------+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1086 \| :const:`PCALL_TYPE` \| 7 \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1087 +-------------------------------+-------+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1088 \| :const:`PCALL_GENERATOR` \| 8 \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1089 +-------------------------------+-------+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1090 \| :const:`PCALL_OTHER` \| 9 \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1091 +-------------------------------+-------+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1092 \| :const:`PCALL_POP` \| 10 \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1093 +-------------------------------+-------+
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	1094
44093 4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1095 :const:`PCALL_FAST_FUNCTION` means no argument tuple needs to be created.
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1096 :const:`PCALL_FASTER_FUNCTION` means that the fast-path frame setup code is used.
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1097
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1098 If there is a method call where the call can be optimized by changing
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1099 the argument tuple and calling the function directly, it gets recorded
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1100 twice.
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1101
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1102 This function is only present if Python is compiled with :const:`CALL_PROFILE`
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1103 defined.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1104
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1105 .. _advanced-debugging:
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 Advanced Debugger Support
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 .. 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	1111
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1112
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1113 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	1114
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1115
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	1116 .. c:function:: PyInterpreterState* PyInterpreterState_Head()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1117
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1118 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	1119
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1120 .. versionadded:: 2.2
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1121
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1122
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	1123 .. 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	1124
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1125 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	1126 such objects.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1127
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1128 .. versionadded:: 2.2
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1129
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1130
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	1131 .. 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	1132
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	1133 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	1134 threads associated with the interpreter interp.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1135
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1136 .. versionadded:: 2.2
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1137
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1138
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	1139 .. 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	1140
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1141 Return the next thread state object after tstate from the list of all such
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74294 diff changeset	1142 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	1143
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1144 .. versionadded:: 2.2
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1145

Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/init.rst @ 79675:c0a2294de787 2.7