Restructure a bit
This commit is contained in:
parent
0765dd6b96
commit
8b50b831b4
|
@ -8,6 +8,10 @@ Initialization, Finalization, and Threads
|
|||
*****************************************
|
||||
|
||||
|
||||
Initializing and finalizing the interpreter
|
||||
===========================================
|
||||
|
||||
|
||||
.. c:function:: void Py_Initialize()
|
||||
|
||||
.. index::
|
||||
|
@ -82,85 +86,8 @@ Initialization, Finalization, and Threads
|
|||
:c:func:`Py_Finalize` more than once.
|
||||
|
||||
|
||||
.. c:function:: PyThreadState* Py_NewInterpreter()
|
||||
|
||||
.. index::
|
||||
module: builtins
|
||||
module: __main__
|
||||
module: sys
|
||||
single: stdout (in module sys)
|
||||
single: stderr (in module sys)
|
||||
single: stdin (in module sys)
|
||||
|
||||
Create a new sub-interpreter. This is an (almost) totally separate environment
|
||||
for the execution of Python code. In particular, the new interpreter has
|
||||
separate, independent versions of all imported modules, including the
|
||||
fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`. The
|
||||
table of loaded modules (``sys.modules``) and the module search path
|
||||
(``sys.path``) are also separate. The new environment has no ``sys.argv``
|
||||
variable. It has new standard I/O stream file objects ``sys.stdin``,
|
||||
``sys.stdout`` and ``sys.stderr`` (however these refer to the same underlying
|
||||
file descriptors).
|
||||
|
||||
The return value points to the first thread state created in the new
|
||||
sub-interpreter. This thread state is made in the current thread state.
|
||||
Note that no actual thread is created; see the discussion of thread states
|
||||
below. If creation of the new interpreter is unsuccessful, *NULL* is
|
||||
returned; no exception is set since the exception state is stored in the
|
||||
current thread state and there may not be a current thread state. (Like all
|
||||
other Python/C API functions, the global interpreter lock must be held before
|
||||
calling this function and is still held when it returns; however, unlike most
|
||||
other Python/C API functions, there needn't be a current thread state on
|
||||
entry.)
|
||||
|
||||
.. index::
|
||||
single: Py_Finalize()
|
||||
single: Py_Initialize()
|
||||
|
||||
Extension modules are shared between (sub-)interpreters as follows: the first
|
||||
time a particular extension is imported, it is initialized normally, and a
|
||||
(shallow) copy of its module's dictionary is squirreled away. When the same
|
||||
extension is imported by another (sub-)interpreter, a new module is initialized
|
||||
and filled with the contents of this copy; the extension's ``init`` function is
|
||||
not called. Note that this is different from what happens when an extension is
|
||||
imported after the interpreter has been completely re-initialized by calling
|
||||
:c:func:`Py_Finalize` and :c:func:`Py_Initialize`; in that case, the extension's
|
||||
``initmodule`` function *is* called again.
|
||||
|
||||
.. index:: single: close() (in module os)
|
||||
|
||||
**Bugs and caveats:** Because sub-interpreters (and the main interpreter) are
|
||||
part of the same process, the insulation between them isn't perfect --- for
|
||||
example, using low-level file operations like :func:`os.close` they can
|
||||
(accidentally or maliciously) affect each other's open files. Because of the
|
||||
way extensions are shared between (sub-)interpreters, some extensions may not
|
||||
work properly; this is especially likely when the extension makes use of
|
||||
(static) global variables, or when the extension manipulates its module's
|
||||
dictionary after its initialization. It is possible to insert objects created
|
||||
in one sub-interpreter into a namespace of another sub-interpreter; this should
|
||||
be done with great care to avoid sharing user-defined functions, methods,
|
||||
instances or classes between sub-interpreters, since import operations executed
|
||||
by such objects may affect the wrong (sub-)interpreter's dictionary of loaded
|
||||
modules. (XXX This is a hard-to-fix bug that will be addressed in a future
|
||||
release.)
|
||||
|
||||
Also note that the use of this functionality is incompatible with extension
|
||||
modules such as PyObjC and ctypes that use the :c:func:`PyGILState_\*` APIs (and
|
||||
this is inherent in the way the :c:func:`PyGILState_\*` functions work). Simple
|
||||
things may work, but confusing behavior will always be near.
|
||||
|
||||
|
||||
.. c:function:: void Py_EndInterpreter(PyThreadState *tstate)
|
||||
|
||||
.. index:: single: Py_Finalize()
|
||||
|
||||
Destroy the (sub-)interpreter represented by the given thread state. The given
|
||||
thread state must be the current thread state. See the discussion of thread
|
||||
states below. When the call returns, the current thread state is *NULL*. All
|
||||
thread states associated with this interpreter are destroyed. (The global
|
||||
interpreter lock must be held before calling this function and is still held
|
||||
when it returns.) :c:func:`Py_Finalize` will destroy all sub-interpreters that
|
||||
haven't been explicitly destroyed at that point.
|
||||
Process-wide parameters
|
||||
=======================
|
||||
|
||||
|
||||
.. c:function:: void Py_SetProgramName(wchar_t *name)
|
||||
|
@ -581,6 +508,7 @@ being held by a thread that is defunct after the fork.
|
|||
:c:func:`PyOS_AfterFork` tries to reset the necessary locks, but is not
|
||||
always able to.
|
||||
|
||||
|
||||
.. c:type:: PyInterpreterState
|
||||
|
||||
This data structure represents the state shared by a number of cooperating
|
||||
|
@ -848,6 +776,99 @@ been created.
|
|||
:c:func:`PyGILState_Release` on the same thread.
|
||||
|
||||
|
||||
Sub-interpreter support
|
||||
=======================
|
||||
|
||||
While in most uses, you will only embed a single Python interpreter, there
|
||||
are cases where you need to create several independent interpreters in the
|
||||
same process and perhaps even in the same thread. Sub-interpreters allow
|
||||
you to do that.
|
||||
|
||||
|
||||
.. c:function:: PyThreadState* Py_NewInterpreter()
|
||||
|
||||
.. index::
|
||||
module: builtins
|
||||
module: __main__
|
||||
module: sys
|
||||
single: stdout (in module sys)
|
||||
single: stderr (in module sys)
|
||||
single: stdin (in module sys)
|
||||
|
||||
Create a new sub-interpreter. This is an (almost) totally separate environment
|
||||
for the execution of Python code. In particular, the new interpreter has
|
||||
separate, independent versions of all imported modules, including the
|
||||
fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`. The
|
||||
table of loaded modules (``sys.modules``) and the module search path
|
||||
(``sys.path``) are also separate. The new environment has no ``sys.argv``
|
||||
variable. It has new standard I/O stream file objects ``sys.stdin``,
|
||||
``sys.stdout`` and ``sys.stderr`` (however these refer to the same underlying
|
||||
file descriptors).
|
||||
|
||||
The return value points to the first thread state created in the new
|
||||
sub-interpreter. This thread state is made in the current thread state.
|
||||
Note that no actual thread is created; see the discussion of thread states
|
||||
below. If creation of the new interpreter is unsuccessful, *NULL* is
|
||||
returned; no exception is set since the exception state is stored in the
|
||||
current thread state and there may not be a current thread state. (Like all
|
||||
other Python/C API functions, the global interpreter lock must be held before
|
||||
calling this function and is still held when it returns; however, unlike most
|
||||
other Python/C API functions, there needn't be a current thread state on
|
||||
entry.)
|
||||
|
||||
.. index::
|
||||
single: Py_Finalize()
|
||||
single: Py_Initialize()
|
||||
|
||||
Extension modules are shared between (sub-)interpreters as follows: the first
|
||||
time a particular extension is imported, it is initialized normally, and a
|
||||
(shallow) copy of its module's dictionary is squirreled away. When the same
|
||||
extension is imported by another (sub-)interpreter, a new module is initialized
|
||||
and filled with the contents of this copy; the extension's ``init`` function is
|
||||
not called. Note that this is different from what happens when an extension is
|
||||
imported after the interpreter has been completely re-initialized by calling
|
||||
:c:func:`Py_Finalize` and :c:func:`Py_Initialize`; in that case, the extension's
|
||||
``initmodule`` function *is* called again.
|
||||
|
||||
.. index:: single: close() (in module os)
|
||||
|
||||
|
||||
.. c:function:: void Py_EndInterpreter(PyThreadState *tstate)
|
||||
|
||||
.. index:: single: Py_Finalize()
|
||||
|
||||
Destroy the (sub-)interpreter represented by the given thread state. The given
|
||||
thread state must be the current thread state. See the discussion of thread
|
||||
states below. When the call returns, the current thread state is *NULL*. All
|
||||
thread states associated with this interpreter are destroyed. (The global
|
||||
interpreter lock must be held before calling this function and is still held
|
||||
when it returns.) :c:func:`Py_Finalize` will destroy all sub-interpreters that
|
||||
haven't been explicitly destroyed at that point.
|
||||
|
||||
|
||||
Bugs and caveats
|
||||
----------------
|
||||
|
||||
Because sub-interpreters (and the main interpreter) are part of the same
|
||||
process, the insulation between them isn't perfect --- for example, using
|
||||
low-level file operations like :func:`os.close` they can
|
||||
(accidentally or maliciously) affect each other's open files. Because of the
|
||||
way extensions are shared between (sub-)interpreters, some extensions may not
|
||||
work properly; this is especially likely when the extension makes use of
|
||||
(static) global variables, or when the extension manipulates its module's
|
||||
dictionary after its initialization. It is possible to insert objects created
|
||||
in one sub-interpreter into a namespace of another sub-interpreter; this should
|
||||
be done with great care to avoid sharing user-defined functions, methods,
|
||||
instances or classes between sub-interpreters, since import operations executed
|
||||
by such objects may affect the wrong (sub-)interpreter's dictionary of loaded
|
||||
modules. (XXX This is a hard-to-fix bug that will be addressed in a future
|
||||
release.)
|
||||
|
||||
Also note that the use of this functionality is incompatible with extension
|
||||
modules such as PyObjC and ctypes that use the :c:func:`PyGILState_\*` APIs (and
|
||||
this is inherent in the way the :c:func:`PyGILState_\*` functions work). Simple
|
||||
things may work, but confusing behavior will always be near.
|
||||
|
||||
|
||||
Asynchronous Notifications
|
||||
==========================
|
||||
|
|
Loading…
Reference in New Issue