diff options
| -rw-r--r-- | Doc/c-api/init.rst | 179 |
1 files changed, 100 insertions, 79 deletions
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index f35df87..0ec1141 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -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 ========================== |