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

annotate Doc/c-api/init.rst @ 54294:dba767bc3155 legacy-trunk

remove mention of old ctypes version

author	Benjamin Peterson <benjamin@python.org>
date	Sat, 23 May 2009 20:59:09 +0000
parents	9e09783ce228
children	d9b5b7dd82a2

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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11 .. cfunction:: void Py_Initialize()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14 single: Py_SetProgramName()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15 single: PyEval_InitThreads()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16 single: PyEval_ReleaseLock()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17 single: PyEval_AcquireLock()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 single: modules (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19 single: path (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20 module: __builtin__
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 module: __main__
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22 module: sys
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23 triple: module; search; path
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 single: PySys_SetArgv()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 single: Py_Finalize()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27 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	28 should be called before using any other Python/C API functions; with the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29 exception of :cfunc:`Py_SetProgramName`, :cfunc:`PyEval_InitThreads`,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30 :cfunc:`PyEval_ReleaseLock`, and :cfunc:`PyEval_AcquireLock`. This initializes
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31 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	32 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	33 the module search path (``sys.path``). It does not set ``sys.argv``; use
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34 :cfunc:`PySys_SetArgv` for that. This is a no-op when called for a second time
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35 (without calling :cfunc:`Py_Finalize` first). There is no return value; it is a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36 fatal error if the initialization fails.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 .. cfunction:: void Py_InitializeEx(int initsigs)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41 This function works like :cfunc:`Py_Initialize` if initsigs is 1. If
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42 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	43 might be useful when Python is embedded.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45 .. versionadded:: 2.4
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48 .. cfunction:: int Py_IsInitialized()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50 Return true (nonzero) when the Python interpreter has been initialized, false
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51 (zero) if not. After :cfunc:`Py_Finalize` is called, this returns false until
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52 :cfunc:`Py_Initialize` is called again.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55 .. cfunction:: void Py_Finalize()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57 Undo all initializations made by :cfunc:`Py_Initialize` and subsequent use of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58 Python/C API functions, and destroy all sub-interpreters (see
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59 :cfunc:`Py_NewInterpreter` below) that were created and not yet destroyed since
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60 the last call to :cfunc:`Py_Initialize`. Ideally, this frees all memory
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61 allocated by the Python interpreter. This is a no-op when called for a second
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	62 time (without calling :cfunc:`Py_Initialize` again first). There is no return
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63 value; errors during finalization are ignored.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65 This function is provided for a number of reasons. An embedding application
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 might want to restart Python without having to restart the application itself.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67 An application that has loaded the Python interpreter from a dynamically
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68 loadable library (or DLL) might want to free all memory allocated by Python
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69 before unloading the DLL. During a hunt for memory leaks in an application a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 developer might want to free all memory allocated by Python before exiting from
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71 the application.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73 Bugs and caveats: The destruction of modules and objects in modules is done
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74 in random order; this may cause destructors (:meth:`__del__` methods) to fail
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75 when they depend on other objects (even functions) or modules. Dynamically
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76 loaded extension modules loaded by Python are not unloaded. Small amounts of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77 memory allocated by the Python interpreter may not be freed (if you find a leak,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78 please report it). Memory tied up in circular references between objects is not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79 freed. Some memory allocated by extension modules may not be freed. Some
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80 extensions may not work properly if their initialization routine is called more
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81 than once; this can happen if an application calls :cfunc:`Py_Initialize` and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82 :cfunc:`Py_Finalize` more than once.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85 .. cfunction:: PyThreadState* Py_NewInterpreter()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88 module: __builtin__
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89 module: __main__
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90 module: sys
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91 single: stdout (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92 single: stderr (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93 single: stdin (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95 Create a new sub-interpreter. This is an (almost) totally separate environment
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96 for the execution of Python code. In particular, the new interpreter has
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97 separate, independent versions of all imported modules, including the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98 fundamental modules :mod:`__builtin__`, :mod:`__main__` and :mod:`sys`. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99 table of loaded modules (``sys.modules``) and the module search path
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	100 (``sys.path``) are also separate. The new environment has no ``sys.argv``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101 variable. It has new standard I/O stream file objects ``sys.stdin``,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 ``sys.stdout`` and ``sys.stderr`` (however these refer to the same underlying
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103 :ctype:`FILE` structures in the C library).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105 The return value points to the first thread state created in the new
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106 sub-interpreter. This thread state is made in the current thread state.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107 Note that no actual thread is created; see the discussion of thread states
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108 below. If creation of the new interpreter is unsuccessful, NULL is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109 returned; no exception is set since the exception state is stored in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110 current thread state and there may not be a current thread state. (Like all
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111 other Python/C API functions, the global interpreter lock must be held before
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	112 calling this function and is still held when it returns; however, unlike most
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113 other Python/C API functions, there needn't be a current thread state on
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114 entry.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117 single: Py_Finalize()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118 single: Py_Initialize()
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 Extension modules are shared between (sub-)interpreters as follows: the first
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121 time a particular extension is imported, it is initialized normally, and a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122 (shallow) copy of its module's dictionary is squirreled away. When the same
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123 extension is imported by another (sub-)interpreter, a new module is initialized
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124 and filled with the contents of this copy; the extension's ``init`` function is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125 not called. Note that this is different from what happens when an extension is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126 imported after the interpreter has been completely re-initialized by calling
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127 :cfunc:`Py_Finalize` and :cfunc:`Py_Initialize`; in that case, the extension's
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128 ``initmodule`` function is called again.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130 .. index:: single: close() (in module os)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132 Bugs and caveats: Because sub-interpreters (and the main interpreter) are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133 part of the same process, the insulation between them isn't perfect --- for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134 example, using low-level file operations like :func:`os.close` they can
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135 (accidentally or maliciously) affect each other's open files. Because of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136 way extensions are shared between (sub-)interpreters, some extensions may not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137 work properly; this is especially likely when the extension makes use of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138 (static) global variables, or when the extension manipulates its module's
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139 dictionary after its initialization. It is possible to insert objects created
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140 in one sub-interpreter into a namespace of another sub-interpreter; this should
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141 be done with great care to avoid sharing user-defined functions, methods,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142 instances or classes between sub-interpreters, since import operations executed
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	143 by such objects may affect the wrong (sub-)interpreter's dictionary of loaded
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144 modules. (XXX This is a hard-to-fix bug that will be addressed in a future
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145 release.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	147 Also note that the use of this functionality is incompatible with extension
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	148 modules such as PyObjC and ctypes that use the :cfunc:`PyGILState_\*` APIs (and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149 this is inherent in the way the :cfunc:`PyGILState_\*` functions work). Simple
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150 things may work, but confusing behavior will always be near.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153 .. cfunction:: void Py_EndInterpreter(PyThreadState *tstate)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155 .. index:: single: Py_Finalize()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	156
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	157 Destroy the (sub-)interpreter represented by the given thread state. The given
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158 thread state must be the current thread state. See the discussion of thread
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	159 states below. When the call returns, the current thread state is NULL. All
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160 thread states associated with this interpreter are destroyed. (The global
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161 interpreter lock must be held before calling this function and is still held
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162 when it returns.) :cfunc:`Py_Finalize` will destroy all sub-interpreters that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163 haven't been explicitly destroyed at that point.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	165
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	166 .. cfunction:: void Py_SetProgramName(char *name)
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 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	169 single: Py_Initialize()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	170 single: main()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171 single: Py_GetPath()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	172
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	173 This function should be called before :cfunc:`Py_Initialize` is called for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	174 the first time, if it is called at all. It tells the interpreter the value
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	175 of the ``argv[0]`` argument to the :cfunc:`main` function of the program.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	176 This is used by :cfunc:`Py_GetPath` and some other functions below to find
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	177 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	178 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	179 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	180 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	181 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	182
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 .. cfunction:: char* Py_GetProgramName()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186 .. index:: single: Py_SetProgramName()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	188 Return the program name set with :cfunc:`Py_SetProgramName`, or the default.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	189 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	190 value.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	191
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	192
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	193 .. cfunction:: char* Py_GetPrefix()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	194
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	195 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	196 through a number of complicated rules from the program name set with
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197 :cfunc:`Py_SetProgramName` and some environment variables; for example, if the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198 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	199 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	200 value. This corresponds to the :makevar:`prefix` variable in the top-level
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201 :file:`Makefile` and the :option:`--prefix` argument to the :program:`configure`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202 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	203 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	204
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 .. cfunction:: char* Py_GetExecPrefix()
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 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	209 derived through a number of complicated rules from the program name set with
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210 :cfunc:`Py_SetProgramName` and some environment variables; for example, if the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211 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	212 ``'/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	213 should not modify its value. This corresponds to the :makevar:`exec_prefix`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214 variable in the top-level :file:`Makefile` and the :option:`--exec-prefix`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215 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	216 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	217
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 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	219 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	220 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	221 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	222 be installed in :file:`/usr/local`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224 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	225 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	226 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	227 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	228 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	229 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	230 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	231 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	232 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	233 which they were compiled!).
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 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	236 :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	237 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	238 platform.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241 .. cfunction:: char* Py_GetProgramFullPath()
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 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244 single: Py_SetProgramName()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245 single: executable (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247 Return the 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	248 side-effect of deriving the default module search path from the program name
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249 (set by :cfunc:`Py_SetProgramName` above). The returned string points into
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250 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	251 to Python code as ``sys.executable``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	252
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	254 .. cfunction:: char* Py_GetPath()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	255
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	256 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	257 triple: module; search; path
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	258 single: path (in module sys)
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 Return the default module search path; this is computed from the program name
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261 (set by :cfunc:`Py_SetProgramName` above) and some environment variables. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 returned string consists of a series of directory names separated by a platform
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263 dependent delimiter character. The delimiter character is ``':'`` on Unix and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264 Mac OS X, ``';'`` on Windows. The returned string points into static storage;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265 the caller should not modify its value. The value is available to Python code
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266 as the list ``sys.path``, which may be modified to change the future search path
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	267 for loaded modules.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	268
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44110 diff changeset	269 .. XXX should give the exact rules
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	272 .. cfunction:: const char* Py_GetVersion()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	274 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	275 something like ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277 "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	278
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279 .. index:: single: version (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281 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	282 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	283 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	284 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	285
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	287 .. cfunction:: const char* Py_GetBuildNumber()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	288
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	289 Return a string representing the Subversion revision that this Python executable
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	290 was built from. This number is a string because it may contain a trailing 'M'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	291 if Python was built from a mixed revision source tree.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	292
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	293 .. versionadded:: 2.5
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	294
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	295
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	296 .. cfunction:: const char* Py_GetPlatform()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	297
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	298 .. index:: single: platform (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	299
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	300 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	301 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	302 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	303 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	304 ``'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	305 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	306 to Python code as ``sys.platform``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	307
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	308
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	309 .. cfunction:: const char* Py_GetCopyright()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311 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	312
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313 ``'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	315 .. index:: single: copyright (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317 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	318 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	319
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321 .. cfunction:: const char* Py_GetCompiler()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323 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	324 in square brackets, for example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326 "[GCC 2.7.2.2]"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328 .. index:: single: version (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330 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	331 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	332 ``sys.version``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	334
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	335 .. cfunction:: const char* Py_GetBuildInfo()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337 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	338 current Python interpreter instance, for example ::
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 "#67, Aug 1 1997, 22:34:28"
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 .. index:: single: version (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	343
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344 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	345 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	346 ``sys.version``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	347
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	349 .. cfunction:: void PySys_SetArgv(int argc, char **argv)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	350
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	351 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	352 single: main()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	353 single: Py_FatalError()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	354 single: argv (in module sys)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	355
51330 ca423008fa4a #5144: document that PySys_SetArgv prepends the script directory (or the empty string) to sys.path. Georg Brandl <georg@python.org> parents: 50762 diff changeset	356 Set :data:`sys.argv` based on argc and argv. These parameters are
ca423008fa4a #5144: document that PySys_SetArgv prepends the script directory (or the empty string) to sys.path. Georg Brandl <georg@python.org> parents: 50762 diff changeset	357 similar to those passed to the program's :cfunc:`main` function with the
ca423008fa4a #5144: document that PySys_SetArgv prepends the script directory (or the empty string) to sys.path. Georg Brandl <georg@python.org> parents: 50762 diff changeset	358 difference that the first entry should refer to the script file to be
ca423008fa4a #5144: document that PySys_SetArgv prepends the script directory (or the empty string) to sys.path. Georg Brandl <georg@python.org> parents: 50762 diff changeset	359 executed rather than the executable hosting the Python interpreter. If there
ca423008fa4a #5144: document that PySys_SetArgv prepends the script directory (or the empty string) to sys.path. Georg Brandl <georg@python.org> parents: 50762 diff changeset	360 isn't a script that will be run, the first entry in argv can be an empty
ca423008fa4a #5144: document that PySys_SetArgv prepends the script directory (or the empty string) to sys.path. Georg Brandl <georg@python.org> parents: 50762 diff changeset	361 string. If this function fails to initialize :data:`sys.argv`, a fatal
ca423008fa4a #5144: document that PySys_SetArgv prepends the script directory (or the empty string) to sys.path. Georg Brandl <georg@python.org> parents: 50762 diff changeset	362 condition is signalled using :cfunc:`Py_FatalError`.
ca423008fa4a #5144: document that PySys_SetArgv prepends the script directory (or the empty string) to sys.path. Georg Brandl <georg@python.org> parents: 50762 diff changeset	363
ca423008fa4a #5144: document that PySys_SetArgv prepends the script directory (or the empty string) to sys.path. Georg Brandl <georg@python.org> parents: 50762 diff changeset	364 This function also prepends the executed script's path to :data:`sys.path`.
ca423008fa4a #5144: document that PySys_SetArgv prepends the script directory (or the empty string) to sys.path. Georg Brandl <georg@python.org> parents: 50762 diff changeset	365 If no script is executed (in the case of calling ``python -c`` or just the
ca423008fa4a #5144: document that PySys_SetArgv prepends the script directory (or the empty string) to sys.path. Georg Brandl <georg@python.org> parents: 50762 diff changeset	366 interactive interpreter), the empty string is used instead.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	367
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44110 diff changeset	368 .. 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	369 check w/ Guido.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	370
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	371
51338 eeaa259069a3 #5015: document PythonHome API functions. Georg Brandl <georg@python.org> parents: 51330 diff changeset	372 .. cfunction:: void Py_SetPythonHome(char *home)
eeaa259069a3 #5015: document PythonHome API functions. Georg Brandl <georg@python.org> parents: 51330 diff changeset	373
eeaa259069a3 #5015: document PythonHome API functions. Georg Brandl <georg@python.org> parents: 51330 diff changeset	374 Set the default "home" directory, that is, the location of the standard
eeaa259069a3 #5015: document PythonHome API functions. Georg Brandl <georg@python.org> parents: 51330 diff changeset	375 Python libraries. The libraries are searched in
eeaa259069a3 #5015: document PythonHome API functions. Georg Brandl <georg@python.org> parents: 51330 diff changeset	376 :file:`{home}/lib/python{version}` and :file:`{home}/lib/python{version}`.
eeaa259069a3 #5015: document PythonHome API functions. Georg Brandl <georg@python.org> parents: 51330 diff changeset	377
eeaa259069a3 #5015: document PythonHome API functions. Georg Brandl <georg@python.org> parents: 51330 diff changeset	378
eeaa259069a3 #5015: document PythonHome API functions. Georg Brandl <georg@python.org> parents: 51330 diff changeset	379 .. cfunction:: char* Py_GetPythonHome()
eeaa259069a3 #5015: document PythonHome API functions. Georg Brandl <georg@python.org> parents: 51330 diff changeset	380
eeaa259069a3 #5015: document PythonHome API functions. Georg Brandl <georg@python.org> parents: 51330 diff changeset	381 Return the default "home", that is, the value set by a previous call to
eeaa259069a3 #5015: document PythonHome API functions. Georg Brandl <georg@python.org> parents: 51330 diff changeset	382 :cfunc:`Py_SetPythonHome`, or the value of the :envvar:`PYTHONHOME`
eeaa259069a3 #5015: document PythonHome API functions. Georg Brandl <georg@python.org> parents: 51330 diff changeset	383 environment variable if it is set.
eeaa259069a3 #5015: document PythonHome API functions. Georg Brandl <georg@python.org> parents: 51330 diff changeset	384
eeaa259069a3 #5015: document PythonHome API functions. Georg Brandl <georg@python.org> parents: 51330 diff changeset	385
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	386 .. _threads:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	387
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	388 Thread State and the Global Interpreter Lock
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	389 ============================================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	390
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	392 single: global interpreter lock
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	393 single: interpreter lock
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	394 single: lock, interpreter
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	395
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396 The Python interpreter is not fully thread safe. In order to support
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	397 multi-threaded Python programs, there's a global lock, called the :dfn:`global
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	398 interpreter lock` or :dfn:`GIL`, that must be held by the current thread before
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	399 it can safely access Python objects. Without the lock, even the simplest
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	400 operations could cause problems in a multi-threaded program: for example, when
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	401 two threads simultaneously increment the reference count of the same object, the
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	402 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	403
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	404 .. index:: single: setcheckinterval() (in module sys)
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 Therefore, the rule exists that only the thread that has acquired the global
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	407 interpreter lock may operate on Python objects or call Python/C API functions.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408 In order to support multi-threaded Python programs, the interpreter regularly
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	409 releases and reacquires the lock --- by default, every 100 bytecode instructions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	410 (this can be changed with :func:`sys.setcheckinterval`). The lock is also
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411 released and reacquired around potentially blocking I/O operations like reading
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	412 or writing a file, so that other threads can run while the thread that requests
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	413 the I/O is waiting for the I/O operation to complete.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	414
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	415 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	416 single: PyThreadState
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417 single: PyThreadState
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	418
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	419 The Python interpreter needs to keep some bookkeeping information separate per
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	420 thread --- for this it uses a data structure called :ctype:`PyThreadState`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	421 There's one global variable, however: the pointer to the current
53536 9e09783ce228 #5840: dont claim we dont support TLS. Georg Brandl <georg@python.org> parents: 53395 diff changeset	422 :ctype:`PyThreadState` structure. Before the addition of :dfn:`thread-local
9e09783ce228 #5840: dont claim we dont support TLS. Georg Brandl <georg@python.org> parents: 53395 diff changeset	423 storage` (:dfn:`TLS`) the current thread state had to be manipulated
9e09783ce228 #5840: dont claim we dont support TLS. Georg Brandl <georg@python.org> parents: 53395 diff changeset	424 explicitly.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	425
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	426 This is easy enough in most cases. Most code manipulating the global
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427 interpreter lock has the following simple structure::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	429 Save the thread state in a local variable.
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	430 Release the global interpreter lock.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	431 ...Do some blocking I/O operation...
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	432 Reacquire the global interpreter lock.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	433 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	434
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	435 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	436
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	437 Py_BEGIN_ALLOW_THREADS
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	438 ...Do some blocking I/O operation...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	439 Py_END_ALLOW_THREADS
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	440
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	441 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	442 single: Py_BEGIN_ALLOW_THREADS
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	443 single: Py_END_ALLOW_THREADS
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	444
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	445 The :cmacro:`Py_BEGIN_ALLOW_THREADS` macro opens a new block and declares a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	446 hidden local variable; the :cmacro:`Py_END_ALLOW_THREADS` macro closes the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	447 block. Another advantage of using these two macros is that when Python is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	448 compiled without thread support, they are defined empty, thus saving the thread
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	449 state and GIL manipulations.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	450
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	451 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	452
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	453 PyThreadState *_save;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	454
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	455 _save = PyEval_SaveThread();
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	456 ...Do some blocking I/O operation...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	457 PyEval_RestoreThread(_save);
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 Using even lower level primitives, we can get roughly the same effect as
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	460 follows::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	461
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	462 PyThreadState *_save;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	463
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	464 _save = PyThreadState_Swap(NULL);
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	465 PyEval_ReleaseLock();
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	466 ...Do some blocking I/O operation...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	467 PyEval_AcquireLock();
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	468 PyThreadState_Swap(_save);
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	469
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	470 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	471 single: PyEval_RestoreThread()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	472 single: errno
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	473 single: PyEval_SaveThread()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	474 single: PyEval_ReleaseLock()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	475 single: PyEval_AcquireLock()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	476
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	477 There are some subtle differences; in particular, :cfunc:`PyEval_RestoreThread`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	478 saves and restores the value of the global variable :cdata:`errno`, since the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	479 lock manipulation does not guarantee that :cdata:`errno` is left alone. Also,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	480 when thread support is disabled, :cfunc:`PyEval_SaveThread` and
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	481 :cfunc:`PyEval_RestoreThread` don't manipulate the GIL; in this case,
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	482 :cfunc:`PyEval_ReleaseLock` and :cfunc:`PyEval_AcquireLock` are not available.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	483 This is done so that dynamically loaded extensions compiled with thread support
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	484 enabled can be loaded by an interpreter that was compiled with disabled thread
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	485 support.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	486
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	487 The global interpreter lock is used to protect the pointer to the current thread
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	488 state. When releasing the lock and saving the thread state, the current thread
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	489 state pointer must be retrieved before the lock is released (since another
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	490 thread could immediately acquire the lock and store its own thread state in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	491 global variable). Conversely, when acquiring the lock and restoring the thread
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	492 state, the lock must be acquired before storing the thread state pointer.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	493
53395 05de864077ba Rewrite a sentence to be more in line with the rest of the documentation with Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 52885 diff changeset	494 It is important to note that when threads are created from C, they don't have
05de864077ba Rewrite a sentence to be more in line with the rest of the documentation with Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 52885 diff changeset	495 the global interpreter lock, nor is there a thread state data structure for
05de864077ba Rewrite a sentence to be more in line with the rest of the documentation with Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 52885 diff changeset	496 them. Such threads must bootstrap themselves into existence, by first
05de864077ba Rewrite a sentence to be more in line with the rest of the documentation with Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 52885 diff changeset	497 creating a thread state data structure, then acquiring the lock, and finally
05de864077ba Rewrite a sentence to be more in line with the rest of the documentation with Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 52885 diff changeset	498 storing their thread state pointer, before they can start using the Python/C
05de864077ba Rewrite a sentence to be more in line with the rest of the documentation with Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 52885 diff changeset	499 API. When they are done, they should reset the thread state pointer, release
05de864077ba Rewrite a sentence to be more in line with the rest of the documentation with Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 52885 diff changeset	500 the lock, and finally free their thread state data structure.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	501
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	502 Beginning with version 2.3, threads can now take advantage of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	503 :cfunc:`PyGILState_\*` functions to do all of the above automatically. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	504 typical idiom for calling into Python from a C thread is now::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	505
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	506 PyGILState_STATE gstate;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	507 gstate = PyGILState_Ensure();
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	508
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	509 /* Perform Python actions here. */
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	510 result = CallSomeFunction();
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	511 /* evaluate result */
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	512
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	513 /* 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	514 PyGILState_Release(gstate);
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	515
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	516 Note that the :cfunc:`PyGILState_\*` functions assume there is only one global
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	517 interpreter (created automatically by :cfunc:`Py_Initialize`). Python still
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	518 supports the creation of additional interpreters (using
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	519 :cfunc:`Py_NewInterpreter`), but mixing multiple interpreters and the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	520 :cfunc:`PyGILState_\*` API is unsupported.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	521
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	522
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	523 .. ctype:: PyInterpreterState
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	524
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	525 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	526 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	527 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	528 this structure.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	529
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	530 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	531 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	532 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	533 interpreter they belong.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	534
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	535
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	536 .. ctype:: PyThreadState
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	537
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	538 This data structure represents the state of a single thread. The only public
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	539 data member is :ctype:`PyInterpreterState \*`:attr:`interp`, which points to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	540 this thread's interpreter state.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	541
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	542
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	543 .. cfunction:: void PyEval_InitThreads()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	544
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	545 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	546 single: PyEval_ReleaseLock()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	547 single: PyEval_ReleaseThread()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	548 single: PyEval_SaveThread()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	549 single: PyEval_RestoreThread()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	550
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	551 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	552 main thread before creating a second thread or engaging in any other thread
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	553 operations such as :cfunc:`PyEval_ReleaseLock` or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	554 ``PyEval_ReleaseThread(tstate)``. It is not needed before calling
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	555 :cfunc:`PyEval_SaveThread` or :cfunc:`PyEval_RestoreThread`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	556
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	557 .. index:: single: Py_Initialize()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	558
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	559 This is a no-op when called for a second time. It is safe to call this function
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	560 before calling :cfunc:`Py_Initialize`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	561
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	562 .. index:: module: thread
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	563
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	564 When only the main thread exists, no GIL operations are needed. This is a
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	565 common situation (most Python programs do not use threads), and the lock
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	566 operations slow the interpreter down a bit. Therefore, the lock is not
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	567 created initially. This situation is equivalent to having acquired the lock:
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	568 when there is only a single thread, all object accesses are safe. Therefore,
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	569 when this function initializes the global interpreter lock, it also acquires
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	570 it. Before the Python :mod:`thread` module creates a new thread, knowing
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	571 that either it has the lock or the lock hasn't been created yet, it calls
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	572 :cfunc:`PyEval_InitThreads`. When this call returns, it is guaranteed that
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	573 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	574
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	575 It is not safe to call this function when it is unknown which thread (if
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	576 any) currently has the global interpreter lock.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	577
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	578 This function is 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	579
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	580
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	581 .. cfunction:: int PyEval_ThreadsInitialized()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	582
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	583 Returns a non-zero value if :cfunc:`PyEval_InitThreads` has been called. This
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	584 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	585 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	586 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	587
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	588 .. versionadded:: 2.4
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	589
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	590
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	591 .. cfunction:: void PyEval_AcquireLock()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	592
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	593 Acquire the global interpreter lock. The lock must have been created earlier.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	594 If this thread already has the lock, a deadlock ensues. This function is not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	595 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	596
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	597
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	598 .. cfunction:: void PyEval_ReleaseLock()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	599
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	600 Release the global interpreter lock. The lock must have been created earlier.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	601 This function is 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	602
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	603
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	604 .. cfunction:: void PyEval_AcquireThread(PyThreadState *tstate)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	605
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	606 Acquire the global interpreter lock and set the current thread state to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	607 tstate, which should not be NULL. The lock must have been created earlier.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	608 If this thread already has the lock, deadlock ensues. This function is not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	609 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	610
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	611
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	612 .. cfunction:: void PyEval_ReleaseThread(PyThreadState *tstate)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	613
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	614 Reset the current thread state to NULL and release the global interpreter
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	615 lock. The lock must have been created earlier and must be held by the current
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	616 thread. The tstate argument, which must not be NULL, is only used to check
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	617 that it represents the current thread state --- if it isn't, a fatal error is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	618 reported. This function is not available when thread support is disabled at
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	619 compile time.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	620
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	621
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	622 .. cfunction:: PyThreadState* PyEval_SaveThread()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	623
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	624 Release the global interpreter lock (if it has been created and thread
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	625 support is enabled) and reset the thread state to NULL, returning the
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	626 previous thread state (which is not NULL). If the lock has been created,
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	627 the current thread must have acquired it. (This function is available even
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	628 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	629
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	630
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	631 .. cfunction:: void PyEval_RestoreThread(PyThreadState *tstate)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	632
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	633 Acquire the global interpreter lock (if it has been created and thread
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	634 support is enabled) and set the thread state to tstate, which must not be
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	635 NULL. If the lock has been created, the current thread must not have
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	636 acquired it, otherwise deadlock ensues. (This function is available even
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	637 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	638
44093 4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	639
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	640 .. cfunction:: void PyEval_ReInitThreads()
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	641
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	642 This function is called from :cfunc:`PyOS_AfterFork` to ensure that newly
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	643 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	644 are not running in the child process.
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	645
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	646
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	647 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	648 example usage in the Python source distribution.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	649
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	650
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	651 .. cmacro:: Py_BEGIN_ALLOW_THREADS
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	652
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	653 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	654 Note that it contains an opening brace; it must be matched with a following
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	655 :cmacro:`Py_END_ALLOW_THREADS` macro. See above for further discussion of this
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	656 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	657
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	658
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	659 .. cmacro:: Py_END_ALLOW_THREADS
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	660
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	661 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	662 a closing brace; it must be matched with an earlier
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	663 :cmacro:`Py_BEGIN_ALLOW_THREADS` macro. See above for further discussion of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	664 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	665
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	666
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	667 .. cmacro:: Py_BLOCK_THREADS
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	668
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	669 This macro expands to ``PyEval_RestoreThread(_save);``: it is equivalent to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	670 :cmacro:`Py_END_ALLOW_THREADS` without the closing brace. It is a no-op when
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	671 thread support is disabled at compile time.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	674 .. cmacro:: Py_UNBLOCK_THREADS
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	675
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	676 This macro expands to ``_save = PyEval_SaveThread();``: it is equivalent to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	677 :cmacro:`Py_BEGIN_ALLOW_THREADS` without the opening brace and variable
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	678 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	679
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	680 All of the following functions are only available when thread support is enabled
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	681 at compile time, and must be called only when the global interpreter lock has
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	682 been created.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	683
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	684
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	685 .. cfunction:: PyInterpreterState* PyInterpreterState_New()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	686
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	687 Create a new interpreter state object. The global interpreter lock need not
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	688 be held, but may be held if it is necessary to serialize calls to this
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	689 function.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	690
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 .. cfunction:: void PyInterpreterState_Clear(PyInterpreterState *interp)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	693
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	694 Reset all information in an interpreter state object. The global interpreter
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	695 lock must be held.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	696
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	697
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	698 .. cfunction:: void PyInterpreterState_Delete(PyInterpreterState *interp)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	699
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	700 Destroy an interpreter state object. The global interpreter lock need not be
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	701 held. The interpreter state must have been reset with a previous call to
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	702 :cfunc:`PyInterpreterState_Clear`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	703
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 .. cfunction:: PyThreadState* PyThreadState_New(PyInterpreterState *interp)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	706
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	707 Create a new thread state object belonging to the given interpreter object.
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	708 The global interpreter lock need not be held, but may be held if it is
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	709 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	710
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 .. cfunction:: void PyThreadState_Clear(PyThreadState *tstate)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	713
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	714 Reset all information in a thread state object. The global interpreter lock
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	715 must be held.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	716
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	717
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	718 .. cfunction:: void PyThreadState_Delete(PyThreadState *tstate)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	719
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	720 Destroy a thread state object. The global interpreter lock need not be held.
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	721 The thread state must have been reset with a previous call to
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	722 :cfunc:`PyThreadState_Clear`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	723
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 .. cfunction:: PyThreadState* PyThreadState_Get()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	726
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	727 Return the current thread state. The global interpreter lock must be held.
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	728 When the current thread state is NULL, this issues a fatal error (so that
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	729 the caller needn't check for NULL).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	730
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	731
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	732 .. cfunction:: PyThreadState* PyThreadState_Swap(PyThreadState *tstate)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	733
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	734 Swap the current thread state with the thread state given by the argument
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	735 tstate, which may be NULL. The global interpreter lock must be held.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	736
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	737
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	738 .. cfunction:: PyObject* PyThreadState_GetDict()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	739
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	740 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	741 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	742 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	743 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	744 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	745
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	746 .. versionchanged:: 2.3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	747 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	748 meant that an exception was raised.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	749
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	750
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	751 .. cfunction:: int PyThreadState_SetAsyncExc(long id, PyObject *exc)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	752
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	753 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	754 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	755 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	756 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	757 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	758 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	759 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	760
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	761 .. versionadded:: 2.3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	762
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	763
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	764 .. cfunction:: PyGILState_STATE PyGILState_Ensure()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	765
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	766 Ensure that the current thread is ready to call the Python C API regardless
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	767 of the current state of Python, or of the global interpreter lock. This may
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	768 be called as many times as desired by a thread as long as each call is
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	769 matched with a call to :cfunc:`PyGILState_Release`. In general, other
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	770 thread-related APIs may be used between :cfunc:`PyGILState_Ensure` and
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	771 :cfunc:`PyGILState_Release` calls as long as the thread state is restored to
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	772 its previous state before the Release(). For example, normal usage of the
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	773 :cmacro:`Py_BEGIN_ALLOW_THREADS` and :cmacro:`Py_END_ALLOW_THREADS` macros is
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	774 acceptable.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	775
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	776 The return value is an opaque "handle" to the thread state when
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 44383 diff changeset	777 :cfunc:`PyGILState_Ensure` was called, and must be passed to
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	778 :cfunc:`PyGILState_Release` to ensure Python is left in the same state. Even
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	779 though recursive calls are allowed, these handles cannot be shared - each
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 44383 diff changeset	780 unique call to :cfunc:`PyGILState_Ensure` must save the handle for its call
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 44383 diff changeset	781 to :cfunc:`PyGILState_Release`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	782
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	783 When the function returns, the current thread will hold the GIL. Failure is a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	784 fatal error.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	785
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	786 .. versionadded:: 2.3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	787
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	788
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	789 .. cfunction:: void PyGILState_Release(PyGILState_STATE)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	790
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	791 Release any resources previously acquired. After this call, Python's state will
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	792 be the same as it was prior to the corresponding :cfunc:`PyGILState_Ensure` call
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	793 (but generally this state will be unknown to the caller, hence the use of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	794 GILState API.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	795
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	796 Every call to :cfunc:`PyGILState_Ensure` must be matched by a call to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	797 :cfunc:`PyGILState_Release` on the same thread.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	798
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	799 .. versionadded:: 2.3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	800
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	801
50675 e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	802
e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	803 Asynchronous Notifications
e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	804 ==========================
e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	805
52777 44954e6a1353 Fix 'the the' duplication Andrew M. Kuchling <amk@amk.ca> parents: 52143 diff changeset	806 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	807 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	808 pointer and a void argument.
e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	809
e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	810 .. 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	811
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	812 Every check interval, when the global interpreter lock is released and
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	813 reacquired, python will also call any such provided functions. This can be used
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	814 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	815 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	816 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	817 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	818
50762 a19d596d3500 Fix call signature and markup. Georg Brandl <georg@python.org> parents: 50675 diff changeset	819 .. cfunction:: void 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	820
e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	821 .. index:: single: Py_AddPendingCall()
e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	822
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	823 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	824 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	825 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	826 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	827 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	828 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	829 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	830 switch threads if the global interpreter lock is released, for example, if it
bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	831 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	832
e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	833 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	834 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	835 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	836
52885 bd1336a3a686 #5298: clarify docs about GIL by using more consistent wording. Georg Brandl <georg@python.org> parents: 52777 diff changeset	837 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	838 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	839 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	840
e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	841 .. versionadded:: 2.7
e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	842
e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	843
e6f55c9ec3d0 Issue 4293: Make Py_AddPendingCall() thread safe Kristján Valur Jónsson <kristjan@ccpgames.com> parents: 50522 diff changeset	844
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	845 .. _profiling:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	846
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	847 Profiling and Tracing
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	848 =====================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	849
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	850 .. 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	851
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	852
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	853 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	854 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	855 coverage analysis tools.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	856
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	857 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	858 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	859 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	860 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	861 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	862 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	863 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	864 in previous versions.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	865
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	866
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	867 .. ctype:: int (Py_tracefunc)(PyObject obj, PyFrameObject frame, int what, PyObject arg)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	868
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	869 The type of the trace function registered using :cfunc:`PyEval_SetProfile` and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	870 :cfunc:`PyEval_SetTrace`. The first parameter is the object passed to the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	871 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	872 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	873 :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	874 :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	875 :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	876
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	877 +------------------------------+--------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	878 \| Value of what \| Meaning of arg \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	879 +==============================+======================================+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	880 \| :const:`PyTrace_CALL` \| Always NULL. \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	881 +------------------------------+--------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	882 \| :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	883 \| \| :func:`sys.exc_info`. \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	884 +------------------------------+--------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	885 \| :const:`PyTrace_LINE` \| Always NULL. \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	886 +------------------------------+--------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	887 \| :const:`PyTrace_RETURN` \| Value being returned to the caller. \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	888 +------------------------------+--------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	889 \| :const:`PyTrace_C_CALL` \| Name of function being called. \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	890 +------------------------------+--------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	891 \| :const:`PyTrace_C_EXCEPTION` \| Always NULL. \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	892 +------------------------------+--------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	893 \| :const:`PyTrace_C_RETURN` \| Always NULL. \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	894 +------------------------------+--------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	895
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	896
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	897 .. cvar:: int PyTrace_CALL
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	898
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	899 The value of the what parameter to a :ctype:`Py_tracefunc` function when a new
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	900 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	901 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	902 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	903 frame.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	904
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	905
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	906 .. cvar:: int PyTrace_EXCEPTION
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	907
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	908 The value of the what parameter to a :ctype:`Py_tracefunc` function when an
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	909 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	910 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	911 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	912 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	913 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	914 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	915
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	916
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	917 .. cvar:: int PyTrace_LINE
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	918
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	919 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	920 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	921
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	922
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	923 .. cvar:: int PyTrace_RETURN
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	924
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	925 The value for the what parameter to :ctype:`Py_tracefunc` functions when a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	926 call is returning without propagating an exception.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	927
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	928
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	929 .. cvar:: int PyTrace_C_CALL
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	930
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	931 The value for the what parameter to :ctype:`Py_tracefunc` functions when a C
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	932 function is about to be called.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	933
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	934
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	935 .. cvar:: int PyTrace_C_EXCEPTION
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	936
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	937 The value for the what parameter to :ctype:`Py_tracefunc` functions when a C
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	938 function has thrown an exception.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	939
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	940
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	941 .. cvar:: int PyTrace_C_RETURN
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	942
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	943 The value for the what parameter to :ctype:`Py_tracefunc` functions when a C
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	944 function has returned.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	945
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	946
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	947 .. cfunction:: void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)
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 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	950 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	951 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	952 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	953 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	954 events.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	955
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 .. cfunction:: void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	958
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	959 Set the tracing function to func. This is similar to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	960 :cfunc:`PyEval_SetProfile`, except the tracing function does receive line-number
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	961 events.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	962
44093 4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	963 .. cfunction:: PyObject* PyEval_GetCallStats(PyObject *self)
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	964
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	965 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	966 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	967
44093 4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	968 +-------------------------------+-------+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	969 \| Name \| Value \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	970 +===============================+=======+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	971 \| :const:`PCALL_ALL` \| 0 \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	972 +-------------------------------+-------+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	973 \| :const:`PCALL_FUNCTION` \| 1 \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	974 +-------------------------------+-------+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	975 \| :const:`PCALL_FAST_FUNCTION` \| 2 \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	976 +-------------------------------+-------+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	977 \| :const:`PCALL_FASTER_FUNCTION`\| 3 \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	978 +-------------------------------+-------+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	979 \| :const:`PCALL_METHOD` \| 4 \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	980 +-------------------------------+-------+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	981 \| :const:`PCALL_BOUND_METHOD` \| 5 \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	982 +-------------------------------+-------+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	983 \| :const:`PCALL_CFUNCTION` \| 6 \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	984 +-------------------------------+-------+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	985 \| :const:`PCALL_TYPE` \| 7 \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	986 +-------------------------------+-------+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	987 \| :const:`PCALL_GENERATOR` \| 8 \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	988 +-------------------------------+-------+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	989 \| :const:`PCALL_OTHER` \| 9 \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	990 +-------------------------------+-------+
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	991 \| :const:`PCALL_POP` \| 10 \|
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	992 +-------------------------------+-------+
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	993
44093 4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	994 :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	995 :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	996
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	997 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	998 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	999 twice.
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1000
4f1b20ed98e5 Document PyEval_* functions from ceval.c. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1001 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	1002 defined.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1003
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1004 .. _advanced-debugging:
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 Advanced Debugger Support
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1007 =========================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1008
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1009 .. 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	1010
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1011
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1012 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	1013
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1014
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1015 .. cfunction:: PyInterpreterState* PyInterpreterState_Head()
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 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	1018
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1019 .. versionadded:: 2.2
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1020
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1021
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1022 .. cfunction:: PyInterpreterState* PyInterpreterState_Next(PyInterpreterState *interp)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1023
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1024 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	1025 such objects.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1026
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1027 .. versionadded:: 2.2
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1030 .. cfunction:: PyThreadState * PyInterpreterState_ThreadHead(PyInterpreterState *interp)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1031
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1032 Return the a pointer to the first :ctype:`PyThreadState` object in the list of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1033 threads associated with the interpreter interp.
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 .. versionadded:: 2.2
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1036
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1037
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1038 .. cfunction:: PyThreadState* PyThreadState_Next(PyThreadState *tstate)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1039
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1040 Return the next thread state object after tstate from the list of all such
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1041 objects belonging to the same :ctype:`PyInterpreterState` object.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1042
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1043 .. versionadded:: 2.2
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1044

Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/init.rst @ 54294:dba767bc3155 legacy-trunk