CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 734 – Multiple Interpreters in the Stdlib | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0734/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 734 – Multiple Interpreters in the Stdlib | peps.python.org'> <meta property="og:description" content="This PEP proposes to add a new module, interpreters, to support inspecting, creating, and running code in multiple interpreters in the current process. This includes Interpreter objects that represent the underlying interpreters. The module will also ..."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0734/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="This PEP proposes to add a new module, interpreters, to support inspecting, creating, and running code in multiple interpreters in the current process. This includes Interpreter objects that represent the underlying interpreters. The module will also ..."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 734</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 734 – Multiple Interpreters in the Stdlib</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Eric Snow <ericsnowcurrently at gmail.com></dd> <dt class="field-even">Discussions-To:</dt> <dd class="field-even"><a class="reference external" href="https://discuss.python.org/t/pep-734-multiple-interpreters-in-the-stdlib/41147">Discourse thread</a></dd> <dt class="field-odd">Status:</dt> <dd class="field-odd"><abbr title="Inactive draft that may be taken up again at a later time">Deferred</abbr></dd> <dt class="field-even">Type:</dt> <dd class="field-even"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-odd">Created:</dt> <dd class="field-odd">06-Nov-2023</dd> <dt class="field-even">Python-Version:</dt> <dd class="field-even">3.13</dd> <dt class="field-odd">Post-History:</dt> <dd class="field-odd"><a class="reference external" href="https://discuss.python.org/t/pep-734-multiple-interpreters-in-the-stdlib/41147/" title="Discourse thread">14-Dec-2023</a></dd> <dt class="field-even">Replaces:</dt> <dd class="field-even"><a class="reference external" href="../pep-0554/">554</a></dd> <dt class="field-odd">Resolution:</dt> <dd class="field-odd"><a class="reference external" href="https://discuss.python.org/t/pep-734-multiple-interpreters-in-the-stdlib/41147/24">Discourse message</a></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#introduction">Introduction</a><ul> <li><a class="reference internal" href="#threads-and-thread-states">Threads and Thread States</a></li> <li><a class="reference internal" href="#interpreter-states">Interpreter States</a></li> <li><a class="reference internal" href="#interpreters-and-threads">Interpreters and Threads</a></li> <li><a class="reference internal" href="#the-main-interpreter">The “Main” Interpreter</a></li> <li><a class="reference internal" href="#interpreter-isolation">Interpreter Isolation</a></li> <li><a class="reference internal" href="#existing-execution-components">Existing Execution Components</a><ul> <li><a class="reference internal" href="#builtins-exec">builtins.exec()</a></li> <li><a class="reference internal" href="#command-line">Command-line</a></li> <li><a class="reference internal" href="#threading-thread">threading.Thread</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#motivation">Motivation</a></li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#using-interpreters">Using Interpreters</a></li> <li><a class="reference internal" href="#interpreter-objects">Interpreter Objects</a></li> <li><a class="reference internal" href="#communicating-between-interpreters">Communicating Between Interpreters</a></li> <li><a class="reference internal" href="#queue-objects">Queue Objects</a></li> <li><a class="reference internal" href="#shareable-objects">Shareable Objects</a></li> <li><a class="reference internal" href="#synchronization">Synchronization</a></li> <li><a class="reference internal" href="#exceptions">Exceptions</a></li> <li><a class="reference internal" href="#interpreterpoolexecutor">InterpreterPoolExecutor</a></li> <li><a class="reference internal" href="#sys-implementation-supports-isolated-interpreters">sys.implementation.supports_isolated_interpreters</a></li> <li><a class="reference internal" href="#examples">Examples</a></li> </ul> </li> <li><a class="reference internal" href="#rationale">Rationale</a><ul> <li><a class="reference internal" href="#a-minimal-api">A Minimal API</a></li> <li><a class="reference internal" href="#create-create-queue">create(), create_queue()</a></li> <li><a class="reference internal" href="#interpreter-prepare-main-sets-multiple-variables">Interpreter.prepare_main() Sets Multiple Variables</a></li> <li><a class="reference internal" href="#propagating-exceptions">Propagating Exceptions</a></li> <li><a class="reference internal" href="#limited-object-sharing">Limited Object Sharing</a></li> <li><a class="reference internal" href="#objects-vs-id-proxies">Objects vs. ID Proxies</a></li> </ul> </li> <li><a class="reference internal" href="#rejected-ideas">Rejected Ideas</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <div class="admonition note"> Note This PEP is essentially a continuation of <a class="pep reference internal" href="../pep-0554/" title="PEP 554 – Multiple Interpreters in the Stdlib">PEP 554</a>. That document had grown a lot of ancillary information across 7 years of discussion. This PEP is a reduction back to the essential information. Much of that extra information is still valid and useful, just not in the immediate context of the specific proposal here. </div> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> This PEP proposes to add a new module, <code class="docutils literal notranslate">interpreters</code>, to support inspecting, creating, and running code in multiple interpreters in the current process. This includes <code class="docutils literal notranslate">Interpreter</code> objects that represent the underlying interpreters. The module will also provide a basic <code class="docutils literal notranslate">Queue</code> class for communication between interpreters. Finally, we will add a new <code class="docutils literal notranslate">concurrent.futures.InterpreterPoolExecutor</code> based on the <code class="docutils literal notranslate">interpreters</code> module. </section> <section id="introduction"> <h2><a class="toc-backref" href="#introduction" role="doc-backlink">Introduction</a></h2> Fundamentally, an “interpreter” is the collection of (essentially) all runtime state which Python threads must share. So, let’s first look at threads. Then we’ll circle back to interpreters. <section id="threads-and-thread-states"> <h3><a class="toc-backref" href="#threads-and-thread-states" role="doc-backlink">Threads and Thread States</a></h3> A Python process will have one or more OS threads running Python code (or otherwise interacting with the C API). Each of these threads interacts with the CPython runtime using its own thread state (<code class="docutils literal notranslate">PyThreadState</code>), which holds all the runtime state unique to that thread. There is also some runtime state that is shared between multiple OS threads. Any OS thread may switch which thread state it is currently using, as long as it isn’t one that another OS thread is already using (or has been using). This “current” thread state is stored by the runtime in a thread-local variable, and may be looked up explicitly with <code class="docutils literal notranslate">PyThreadState_Get()</code>. It gets set automatically for the initial (“main”) OS thread and for <code class="docutils literal notranslate">threading.Thread</code> objects. From the C API it is set (and cleared) by <code class="docutils literal notranslate">PyThreadState_Swap()</code> and may be set by <code class="docutils literal notranslate">PyGILState_Ensure()</code>. Most of the C API requires that there be a current thread state, either looked up implicitly or passed in as an argument. The relationship between OS threads and thread states is one-to-many. Each thread state is associated with at most a single OS thread and records its thread ID. A thread state is never used for more than one OS thread. In the other direction, however, an OS thread may have more than one thread state associated with it, though, again, only one may be current. When there’s more than one thread state for an OS thread, <code class="docutils literal notranslate">PyThreadState_Swap()</code> is used in that OS thread to switch between them, with the requested thread state becoming the current one. Whatever was running in the thread using the old thread state is effectively paused until that thread state is swapped back in. </section> <section id="interpreter-states"> <h3><a class="toc-backref" href="#interpreter-states" role="doc-backlink">Interpreter States</a></h3> As noted earlier, there is some runtime state that multiple OS threads share. Some of it is exposed by the <code class="docutils literal notranslate">sys</code> module, though much is used internally and not exposed explicitly or only through the C API. This shared state is called the interpreter state (<code class="docutils literal notranslate">PyInterpreterState</code>). We’ll sometimes refer to it here as just “interpreter”, though that is also sometimes used to refer to the <code class="docutils literal notranslate">python</code> executable, to the Python implementation, and to the bytecode interpreter (i.e. <code class="docutils literal notranslate">exec()</code>/<code class="docutils literal notranslate">eval()</code>). CPython has supported multiple interpreters in the same process (AKA “subinterpreters”) since version 1.5 (1997). The feature has been available via the <a class="reference external" href="https://docs.python.org/3/c-api/init.html#sub-interpreter-support" title="(in Python v3.13)">C API</a>. </section> <section id="interpreters-and-threads"> <h3><a class="toc-backref" href="#interpreters-and-threads" role="doc-backlink">Interpreters and Threads</a></h3> Thread states are related to interpreter states in much the same way that OS threads and processes are related (at a high level). To begin with, the relationship is one-to-many. A thread state belongs to a single interpreter (and stores a pointer to it). That thread state is never used for a different interpreter. In the other direction, however, an interpreter may have zero or more thread states associated with it. The interpreter is only considered active in OS threads where one of its thread states is current. Interpreters are created via the C API using <code class="docutils literal notranslate">Py_NewInterpreterFromConfig()</code> (or <code class="docutils literal notranslate">Py_NewInterpreter()</code>, which is a light wrapper around <code class="docutils literal notranslate">Py_NewInterpreterFromConfig()</code>). That function does the following: <ol class="arabic simple"> <li>create a new interpreter state</li> <li>create a new thread state</li> <li>set the thread state as current (a current tstate is needed for interpreter init)</li> <li>initialize the interpreter state using that thread state</li> <li>return the thread state (still current)</li> </ol> Note that the returned thread state may be immediately discarded. There is no requirement that an interpreter have any thread states, except as soon as the interpreter is meant to actually be used. At that point it must be made active in the current OS thread. To make an existing interpreter active in the current OS thread, the C API user first makes sure that interpreter has a corresponding thread state. Then <code class="docutils literal notranslate">PyThreadState_Swap()</code> is called like normal using that thread state. If the thread state for another interpreter was already current then it gets swapped out like normal and execution of that interpreter in the OS thread is thus effectively paused until it is swapped back in. Once an interpreter is active in the current OS thread like that, the thread can call any of the C API, such as <code class="docutils literal notranslate">PyEval_EvalCode()</code> (i.e. <code class="docutils literal notranslate">exec()</code>). This works by using the current thread state as the runtime context. </section> <section id="the-main-interpreter"> <h3><a class="toc-backref" href="#the-main-interpreter" role="doc-backlink">The “Main” Interpreter</a></h3> When a Python process starts, it creates a single interpreter state (the “main” interpreter) with a single thread state for the current OS thread. The Python runtime is then initialized using them. After initialization, the script or module or REPL is executed using them. That execution happens in the interpreter’s <code class="docutils literal notranslate">__main__</code> module. When the process finishes running the requested Python code or REPL, in the main OS thread, the Python runtime is finalized in that thread using the main interpreter. Runtime finalization has only a slight, indirect effect on still-running Python threads, whether in the main interpreter or in subinterpreters. That’s because right away it waits indefinitely for all non-daemon Python threads to finish. While the C API may be queried, there is no mechanism by which any Python thread is directly alerted that finalization has begun, other than perhaps with “atexit” functions that may be been registered using <code class="docutils literal notranslate">threading._register_atexit()</code>. Any remaining subinterpreters are themselves finalized later, but at that point they aren’t current in any OS threads. </section> <section id="interpreter-isolation"> <h3><a class="toc-backref" href="#interpreter-isolation" role="doc-backlink">Interpreter Isolation</a></h3> CPython’s interpreters are intended to be strictly isolated from each other. That means interpreters never share objects (except in very specific cases with immortal, immutable builtin objects). Each interpreter has its own modules (<code class="docutils literal notranslate">sys.modules</code>), classes, functions, and variables. Even where two interpreters define the same class, each will have its own copy. The same applies to state in C, including in extension modules. The CPython C API docs <a class="reference external" href="https://docs.python.org/3/c-api/init.html#bugs-and-caveats">explain more</a>. Notably, there is some process-global state that interpreters will always share, some mutable and some immutable. Sharing immutable state presents few problems, while providing some benefits (mainly performance). However, all shared mutable state requires special management, particularly for thread-safety, some of which the OS takes care of for us. Mutable: <ul class="simple"> <li>file descriptors</li> <li>low-level env vars</li> <li>process memory (though allocators are isolated)</li> <li>the list of interpreters</li> </ul> Immutable: <ul class="simple"> <li>builtin types (e.g. <code class="docutils literal notranslate">dict</code>, <code class="docutils literal notranslate">bytes</code>)</li> <li>singletons (e.g. <code class="docutils literal notranslate">None</code>)</li> <li>underlying static module data (e.g. functions) for builtin/extension/frozen modules</li> </ul> </section> <section id="existing-execution-components"> <h3><a class="toc-backref" href="#existing-execution-components" role="doc-backlink">Existing Execution Components</a></h3> There are a number of existing parts of Python that may help with understanding how code may be run in a subinterpreter. In CPython, each component is built around one of the following C API functions (or variants): <ul class="simple"> <li><code class="docutils literal notranslate">PyEval_EvalCode()</code>: run the bytecode interpreter with the given code object</li> <li><code class="docutils literal notranslate">PyRun_String()</code>: compile + <code class="docutils literal notranslate">PyEval_EvalCode()</code></li> <li><code class="docutils literal notranslate">PyRun_File()</code>: read + compile + <code class="docutils literal notranslate">PyEval_EvalCode()</code></li> <li><code class="docutils literal notranslate">PyRun_InteractiveOneObject()</code>: compile + <code class="docutils literal notranslate">PyEval_EvalCode()</code></li> <li><code class="docutils literal notranslate">PyObject_Call()</code>: calls <code class="docutils literal notranslate">PyEval_EvalCode()</code></li> </ul> <section id="builtins-exec"> <h4><a class="toc-backref" href="#builtins-exec" role="doc-backlink">builtins.exec()</a></h4> The builtin <code class="docutils literal notranslate">exec()</code> may be used to execute Python code. It is essentially a wrapper around the C API functions <code class="docutils literal notranslate">PyRun_String()</code> and <code class="docutils literal notranslate">PyEval_EvalCode()</code>. Here are some relevant characteristics of the builtin <code class="docutils literal notranslate">exec()</code>: <ul class="simple"> <li>It runs in the current OS thread and pauses whatever was running there, which resumes when <code class="docutils literal notranslate">exec()</code> finishes. No other OS threads are affected. (To avoid pausing the current Python thread, run <code class="docutils literal notranslate">exec()</code> in a <code class="docutils literal notranslate">threading.Thread</code>.)</li> <li>It may start additional threads, which don’t interrupt it.</li> <li>It executes against a “globals” namespace (and a “locals” namespace). At module-level, <code class="docutils literal notranslate">exec()</code> defaults to using <code class="docutils literal notranslate">__dict__</code> of the current module (i.e. <code class="docutils literal notranslate">globals()</code>). <code class="docutils literal notranslate">exec()</code> uses that namespace as-is and does not clear it before or after.</li> <li>It propagates any uncaught exception from the code it ran. The exception is raised from the <code class="docutils literal notranslate">exec()</code> call in the Python thread that originally called <code class="docutils literal notranslate">exec()</code>.</li> </ul> </section> <section id="command-line"> <h4><a class="toc-backref" href="#command-line" role="doc-backlink">Command-line</a></h4> The <code class="docutils literal notranslate">python</code> CLI provides several ways to run Python code. In each case it maps to a corresponding C API call: <ul class="simple"> <li><code class="docutils literal notranslate"><no args></code>, <code class="docutils literal notranslate">-i</code> - run the REPL (<code class="docutils literal notranslate">PyRun_InteractiveOneObject()</code>)</li> <li><code class="docutils literal notranslate"><filename></code> - run a script (<code class="docutils literal notranslate">PyRun_File()</code>)</li> <li><code class="docutils literal notranslate">-c <code></code> - run the given Python code (<code class="docutils literal notranslate">PyRun_String()</code>)</li> <li><code class="docutils literal notranslate">-m module</code> - run the module as a script (<code class="docutils literal notranslate">PyEval_EvalCode()</code> via <code class="docutils literal notranslate">runpy._run_module_as_main()</code>)</li> </ul> In each case it is essentially a variant of running <code class="docutils literal notranslate">exec()</code> at the top-level of the <code class="docutils literal notranslate">__main__</code> module of the main interpreter. </section> <section id="threading-thread"> <h4><a class="toc-backref" href="#threading-thread" role="doc-backlink">threading.Thread</a></h4> When a Python thread is started, it runs the “target” function with <code class="docutils literal notranslate">PyObject_Call()</code> using a new thread state. The globals namespace come from <code class="docutils literal notranslate">func.__globals__</code> and any uncaught exception is discarded. </section> </section> </section> <section id="motivation"> <h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2> The <code class="docutils literal notranslate">interpreters</code> module will provide a high-level interface to the multiple interpreter functionality. The goal is to make the existing multiple-interpreters feature of CPython more easily accessible to Python code. This is particularly relevant now that CPython has a per-interpreter GIL (<a class="pep reference internal" href="../pep-0684/" title="PEP 684 – A Per-Interpreter GIL">PEP 684</a>) and people are more interested in using multiple interpreters. Without a stdlib module, users are limited to the <a class="reference external" href="https://docs.python.org/3/c-api/init.html#sub-interpreter-support" title="(in Python v3.13)">C API</a>, which restricts how much they can try out and take advantage of multiple interpreters. The module will include a basic mechanism for communicating between interpreters. Without one, multiple interpreters are a much less useful feature. </section> <section id="specification"> <h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2> The module will: <ul class="simple"> <li>expose the existing multiple interpreter support</li> <li>introduce a basic mechanism for communicating between interpreters</li> </ul> The module will wrap a new low-level <code class="docutils literal notranslate">_interpreters</code> module (in the same way as the <code class="docutils literal notranslate">threading</code> module). However, that low-level API is not intended for public use and thus not part of this proposal. <section id="using-interpreters"> <h3><a class="toc-backref" href="#using-interpreters" role="doc-backlink">Using Interpreters</a></h3> The module defines the following functions: <ul class="simple"> <li><dl class="simple"> <dt><code class="docutils literal notranslate">get_current() -> Interpreter</code></dt><dd>Returns the <code class="docutils literal notranslate">Interpreter</code> object for the currently executing interpreter.</dd> </dl> </li> <li><dl class="simple"> <dt><code class="docutils literal notranslate">list_all() -> list[Interpreter]</code></dt><dd>Returns the <code class="docutils literal notranslate">Interpreter</code> object for each existing interpreter, whether it is currently running in any OS threads or not.</dd> </dl> </li> <li><dl class="simple"> <dt><code class="docutils literal notranslate">create() -> Interpreter</code></dt><dd>Create a new interpreter and return the <code class="docutils literal notranslate">Interpreter</code> object for it. The interpreter doesn’t do anything on its own and is not inherently tied to any OS thread. That only happens when something is actually run in the interpreter (e.g. <code class="docutils literal notranslate">Interpreter.exec()</code>), and only while running. The interpreter may or may not have thread states ready to use, but that is strictly an internal implementation detail.</dd> </dl> </li> </ul> </section> <section id="interpreter-objects"> <h3><a class="toc-backref" href="#interpreter-objects" role="doc-backlink">Interpreter Objects</a></h3> An <code class="docutils literal notranslate">interpreters.Interpreter</code> object that represents the interpreter (<code class="docutils literal notranslate">PyInterpreterState</code>) with the corresponding unique ID. There will only be one object for any given interpreter. If the interpreter was created with <code class="docutils literal notranslate">interpreters.create()</code> then it will be destroyed as soon as all <code class="docutils literal notranslate">Interpreter</code> objects with its ID (across all interpreters) have been deleted. <code class="docutils literal notranslate">Interpreter</code> objects may represent other interpreters than those created by <code class="docutils literal notranslate">interpreters.create()</code>. Examples include the main interpreter (created by Python’s runtime initialization) and those created via the C-API, using <code class="docutils literal notranslate">Py_NewInterpreter()</code>. Such <code class="docutils literal notranslate">Interpreter</code> objects will not be able to interact with their corresponding interpreters, e.g. via <code class="docutils literal notranslate">Interpreter.exec()</code> (though we may relax this in the future). Attributes and methods: <ul> <li><dl class="simple"> <dt><code class="docutils literal notranslate">id</code></dt><dd>(read-only) A non-negative <code class="docutils literal notranslate">int</code> that identifies the interpreter that this <code class="docutils literal notranslate">Interpreter</code> instance represents. Conceptually, this is similar to a process ID.</dd> </dl> </li> <li><dl class="simple"> <dt><code class="docutils literal notranslate">__hash__()</code></dt><dd>Returns the hash of the interpreter’s <code class="docutils literal notranslate">id</code>. This is the same as the hash of the ID’s integer value.</dd> </dl> </li> <li><dl> <dt><code class="docutils literal notranslate">is_running() -> bool</code></dt><dd>Returns <code class="docutils literal notranslate">True</code> if the interpreter is currently executing code in its <code class="docutils literal notranslate">__main__</code> module. This excludes sub-threads.It refers only to if there is an OS thread running a script (code) in the interpreter’s <code class="docutils literal notranslate">__main__</code> module. That basically means whether or not <code class="docutils literal notranslate">Interpreter.exec()</code> is running in some OS thread. Code running in sub-threads is ignored. </dd> </dl> </li> <li><dl> <dt><code class="docutils literal notranslate">prepare_main(**kwargs)</code></dt><dd>Bind one or more objects in the interpreter’s <code class="docutils literal notranslate">__main__</code> module.The keyword argument names will be used as the attribute names. The values will be bound as new objects, though exactly equivalent to the original. Only objects specifically supported for passing between interpreters are allowed. See <a class="reference internal" href="#shareable-objects">Shareable Objects</a>. <code class="docutils literal notranslate">prepare_main()</code> is helpful for initializing the globals for an interpreter before running code in it. </dd> </dl> </li> <li><dl> <dt><code class="docutils literal notranslate">exec(code, /)</code></dt><dd>Execute the given source code in the interpreter (in the current OS thread), using its <code class="docutils literal notranslate">__main__</code> module. It doesn’t return anything.This is essentially equivalent to switching to this interpreter in the current OS thread and then calling the builtin <code class="docutils literal notranslate">exec()</code> using this interpreter’s <code class="docutils literal notranslate">__main__</code> module’s <code class="docutils literal notranslate">__dict__</code> as the globals and locals. The code running in the current OS thread (a different interpreter) is effectively paused until <code class="docutils literal notranslate">Interpreter.exec()</code> finishes. To avoid pausing it, create a new <code class="docutils literal notranslate">threading.Thread</code> and call <code class="docutils literal notranslate">Interpreter.exec()</code> in it (like <code class="docutils literal notranslate">Interpreter.call_in_thread()</code> does). <code class="docutils literal notranslate">Interpreter.exec()</code> does not reset the interpreter’s state nor the <code class="docutils literal notranslate">__main__</code> module, neither before nor after, so each successive call picks up where the last one left off. This can be useful for running some code to initialize an interpreter (e.g. with imports) before later performing some repeated task. If there is an uncaught exception, it will be propagated into the calling interpreter as an <code class="docutils literal notranslate">ExecutionFailed</code>. The full error display of the original exception, generated relative to the called interpreter, is preserved on the propagated <code class="docutils literal notranslate">ExecutionFailed</code>. That includes the full traceback, with all the extra info like syntax error details and chained exceptions. If the <code class="docutils literal notranslate">ExecutionFailed</code> is not caught then that full error display will be shown, much like it would be if the propagated exception had been raised in the main interpreter and uncaught. Having the full traceback is particularly useful when debugging. If exception propagation is not desired then an explicit try-except should be used around the code passed to <code class="docutils literal notranslate">Interpreter.exec()</code>. Likewise any error handling that depends on specific information from the exception must use an explicit try-except around the given code, since <code class="docutils literal notranslate">ExecutionFailed</code> will not preserve that information. </dd> </dl> </li> <li><dl> <dt><code class="docutils literal notranslate">call(callable, /)</code></dt><dd>Call the callable object in the interpreter. The return value is discarded. If the callable raises an exception then it gets propagated as an <code class="docutils literal notranslate">ExecutionFailed</code> exception, in the same way as <code class="docutils literal notranslate">Interpreter.exec()</code>.For now only plain functions are supported and only ones that take no arguments and have no cell vars. Free globals are resolved against the target interpreter’s <code class="docutils literal notranslate">__main__</code> module. In the future, we can add support for arguments, closures, and a broader variety of callables, at least partly via pickle. We can also consider not discarding the return value. The initial restrictions are in place to allow us to get the basic functionality of the module out to users sooner. </dd> </dl> </li> <li><dl> <dt><code class="docutils literal notranslate">call_in_thread(callable, /) -> threading.Thread</code></dt><dd>Essentially, apply <code class="docutils literal notranslate">Interpreter.call()</code> in a new thread. Return values are discarded and exceptions are not propagated.<code class="docutils literal notranslate">call_in_thread()</code> is roughly equivalent to: <div class="highlight-default notranslate"><div class="highlight"><pre>def task(): interp.call(func) t = threading.Thread(target=task) t.start() </pre></div> </div> </dd> </dl> </li> <li><dl class="simple"> <dt><code class="docutils literal notranslate">close()</code></dt><dd>Destroy the underlying interpreter.</dd> </dl> </li> </ul> </section> <section id="communicating-between-interpreters"> <h3><a class="toc-backref" href="#communicating-between-interpreters" role="doc-backlink">Communicating Between Interpreters</a></h3> The module introduces a basic communication mechanism through special queues. There are <code class="docutils literal notranslate">interpreters.Queue</code> objects, but they only proxy the actual data structure: an unbounded FIFO queue that exists outside any one interpreter. These queues have special accommodations for safely passing object data between interpreters, without violating interpreter isolation. This includes thread-safety. As with other queues in Python, for each “put” the object is added to the back and each “get” pops the next one off the front. Every added object will be popped off in the order it was pushed on. Only objects that are specifically supported for passing between interpreters may be sent through an <code class="docutils literal notranslate">interpreters.Queue</code>. Note that the actual objects aren’t sent, but rather their underlying data. However, the popped object will still be strictly equivalent to the original. See <a class="reference internal" href="#shareable-objects">Shareable Objects</a>. The module defines the following functions: <ul> <li><dl> <dt><code class="docutils literal notranslate">create_queue(maxsize=0, *, syncobj=False) -> Queue</code></dt><dd>Create a new queue. If the maxsize is zero or negative then the queue is unbounded.“syncobj” is used as the default for <code class="docutils literal notranslate">put()</code> and <code class="docutils literal notranslate">put_nowait()</code>. </dd> </dl> </li> </ul> </section> <section id="queue-objects"> <h3><a class="toc-backref" href="#queue-objects" role="doc-backlink">Queue Objects</a></h3> <code class="docutils literal notranslate">interpreters.Queue</code> objects act as proxies for the underlying cross-interpreter-safe queues exposed by the <code class="docutils literal notranslate">interpreters</code> module. Each <code class="docutils literal notranslate">Queue</code> object represents the queue with the corresponding unique ID. There will only be one object for any given queue. <code class="docutils literal notranslate">Queue</code> implements all the methods of <code class="docutils literal notranslate">queue.Queue</code> except for <code class="docutils literal notranslate">task_done()</code> and <code class="docutils literal notranslate">join()</code>, hence it is similar to <code class="docutils literal notranslate">asyncio.Queue</code> and <code class="docutils literal notranslate">multiprocessing.Queue</code>. Attributes and methods: <ul> <li><dl class="simple"> <dt><code class="docutils literal notranslate">id</code></dt><dd>(read-only) A non-negative <code class="docutils literal notranslate">int</code> that identifies the corresponding cross-interpreter queue. Conceptually, this is similar to the file descriptor used for a pipe.</dd> </dl> </li> <li><dl class="simple"> <dt><code class="docutils literal notranslate">maxsize</code></dt><dd>(read-only) Number of items allowed in the queue. Zero means “unbounded”.</dd> </dl> </li> <li><dl class="simple"> <dt><code class="docutils literal notranslate">__hash__()</code></dt><dd>Return the hash of the queue’s <code class="docutils literal notranslate">id</code>. This is the same as the hash of the ID’s integer value.</dd> </dl> </li> <li><dl> <dt><code class="docutils literal notranslate">empty()</code></dt><dd>Return <code class="docutils literal notranslate">True</code> if the queue is empty, <code class="docutils literal notranslate">False</code> otherwise.This is only a snapshot of the state at the time of the call. Other threads or interpreters may cause this to change. </dd> </dl> </li> <li><dl> <dt><code class="docutils literal notranslate">full()</code></dt><dd>Return <code class="docutils literal notranslate">True</code> if there are <code class="docutils literal notranslate">maxsize</code> items in the queue.If the queue was initialized with <code class="docutils literal notranslate">maxsize=0</code> (the default), then <code class="docutils literal notranslate">full()</code> never returns <code class="docutils literal notranslate">True</code>. This is only a snapshot of the state at the time of the call. Other threads or interpreters may cause this to change. </dd> </dl> </li> <li><dl> <dt><code class="docutils literal notranslate">qsize()</code></dt><dd>Return the number of items in the queue.This is only a snapshot of the state at the time of the call. Other threads or interpreters may cause this to change. </dd> </dl> </li> <li><dl> <dt><code class="docutils literal notranslate">put(obj, timeout=None, *, syncobj=None)</code></dt><dd>Add the object to the queue.If <code class="docutils literal notranslate">maxsize > 0</code> and the queue is full then this blocks until a free slot is available. If timeout is a positive number then it only blocks at least that many seconds and then raises <code class="docutils literal notranslate">interpreters.QueueFull</code>. Otherwise is blocks forever. If “syncobj” is true then the object must be <a class="reference internal" href="#shareable-objects">shareable</a>, which means the object’s data is passed through rather than the object itself. If “syncobj” is false then all objects are supported. However, there are some performance penalties and all objects are copies (e.g. via pickle). Thus mutable objects will never be automatically synchronized between interpreters. If “syncobj” is None (the default) then the queue’s default value is used. If an object is still in the queue, and the interpreter which put it in the queue (i.e. to which it belongs) is destroyed, then the object is immediately removed from the queue. (We may later add an option to replace the removed object in the queue with a sentinel or to raise an exception for the corresponding <code class="docutils literal notranslate">get()</code> call.) </dd> </dl> </li> <li><dl class="simple"> <dt><code class="docutils literal notranslate">put_nowait(obj, *, syncobj=None)</code></dt><dd>Like <code class="docutils literal notranslate">put()</code> but effectively with an immediate timeout. Thus if the queue is full, it immediately raises <code class="docutils literal notranslate">interpreters.QueueFull</code>.</dd> </dl> </li> <li><dl class="simple"> <dt><code class="docutils literal notranslate">get(timeout=None) -> object</code></dt><dd>Pop the next object from the queue and return it. Block while the queue is empty. If a positive timeout is provided and an object hasn’t been added to the queue in that many seconds then raise <code class="docutils literal notranslate">interpreters.QueueEmpty</code>.</dd> </dl> </li> <li><dl class="simple"> <dt><code class="docutils literal notranslate">get_nowait() -> object</code></dt><dd>Like <code class="docutils literal notranslate">get()</code>, but do not block. If the queue is not empty then return the next item. Otherwise, raise <code class="docutils literal notranslate">interpreters.QueueEmpty</code>.</dd> </dl> </li> </ul> </section> <section id="shareable-objects"> <h3><a class="toc-backref" href="#shareable-objects" role="doc-backlink">Shareable Objects</a></h3> <code class="docutils literal notranslate">Interpreter.prepare_main()</code> only works with “shareable” objects. The same goes for <code class="docutils literal notranslate">interpreters.Queue</code> (optionally). A “shareable” object is one which may be passed from one interpreter to another. The object is not necessarily actually directly shared by the interpreters. However, even if it isn’t, the shared object should be treated as though it were shared directly. That’s a strong equivalence guarantee for all shareable objects. (See below.) For some types (builtin singletons), the actual object is shared. For some, the object’s underlying data is actually shared but each interpreter has a distinct object wrapping that data. For all other shareable types, a strict copy or proxy is made such that the corresponding objects continue to match exactly. In cases where the underlying data is complex but must be copied (e.g. <code class="docutils literal notranslate">tuple</code>), the data is serialized as efficiently as possible. Shareable objects must be specifically supported internally by the Python runtime. However, there is no restriction against adding support for more types later. Here’s the initial list of supported objects: <ul class="simple"> <li><code class="docutils literal notranslate">str</code></li> <li><code class="docutils literal notranslate">bytes</code></li> <li><code class="docutils literal notranslate">int</code></li> <li><code class="docutils literal notranslate">float</code></li> <li><code class="docutils literal notranslate">bool</code> (<code class="docutils literal notranslate">True</code>/<code class="docutils literal notranslate">False</code>)</li> <li><code class="docutils literal notranslate">None</code></li> <li><code class="docutils literal notranslate">tuple</code> (only with shareable items)</li> <li><code class="docutils literal notranslate">interpreters.Queue</code></li> <li><code class="docutils literal notranslate">memoryview</code> (underlying buffer actually shared)</li> </ul> Note that the last two on the list, queues and <code class="docutils literal notranslate">memoryview</code>, are technically mutable data types, whereas the rest are not. When any interpreters share mutable data there is always a risk of data races. Cross-interpreter safety, including thread-safety, is a fundamental feature of queues. However, <code class="docutils literal notranslate">memoryview</code> does not have any native accommodations. The user is responsible for managing thread-safety, whether passing a token back and forth through a queue to indicate safety (see <a class="reference internal" href="#synchronization">Synchronization</a>), or by assigning sub-range exclusivity to individual interpreters. Most objects will be shared through queues (<code class="docutils literal notranslate">interpreters.Queue</code>), as interpreters communicate information between each other. Less frequently, objects will be shared through <code class="docutils literal notranslate">prepare_main()</code> to set up an interpreter prior to running code in it. However, <code class="docutils literal notranslate">prepare_main()</code> is the primary way that queues are shared, to provide another interpreter with a means of further communication. Finally, a reminder: for a few types the actual object is shared, whereas for the rest only the underlying data is shared, whether as a copy or through a proxy. Regardless, it always preserves the strong equivalence guarantee of “shareable” objects. The guarantee is that a shared object in one interpreter is strictly equivalent to the corresponding object in the other interpreter. In other words, the two objects will be indistinguishable from each other. The shared object should be treated as though the original had been shared directly, whether or not it actually was. That’s a slightly different and stronger promise than just equality. The guarantee is especially important for mutable objects, like <code class="docutils literal notranslate">Interpreters.Queue</code> and <code class="docutils literal notranslate">memoryview</code>. Mutating the object in one interpreter will always be reflected immediately in every other interpreter sharing the object. </section> <section id="synchronization"> <h3><a class="toc-backref" href="#synchronization" role="doc-backlink">Synchronization</a></h3> There are situations where two interpreters should be synchronized. That may involve sharing a resource, worker management, or preserving sequential consistency. In threaded programming the typical synchronization primitives are types like mutexes. The <code class="docutils literal notranslate">threading</code> module exposes several. However, interpreters cannot share objects which means they cannot share <code class="docutils literal notranslate">threading.Lock</code> objects. The <code class="docutils literal notranslate">interpreters</code> module does not provide any such dedicated synchronization primitives. Instead, <code class="docutils literal notranslate">interpreters.Queue</code> objects provide everything one might need. For example, if there’s a shared resource that needs managed access then a queue may be used to manage it, where the interpreters pass an object around to indicate who can use the resource: <div class="highlight-default notranslate"><div class="highlight"><pre>import interpreters from mymodule import load_big_data, check_data numworkers = 10 control = interpreters.create_queue() data = memoryview(load_big_data()) def worker(): interp = interpreters.create() interp.prepare_main(control=control, data=data) interp.exec("""if True: from mymodule import edit_data while True: token = control.get() edit_data(data) control.put(token) """) threads = [threading.Thread(target=worker) for _ in range(numworkers)] for t in threads: t.start() token = 'football' control.put(token) while True: control.get() if not check_data(data): break control.put(token) </pre></div> </div> </section> <section id="exceptions"> <h3><a class="toc-backref" href="#exceptions" role="doc-backlink">Exceptions</a></h3> <ul> <li><dl> <dt><code class="docutils literal notranslate">InterpreterError</code></dt><dd>Indicates that some interpreter-related failure occurred.This exception is a subclass of <code class="docutils literal notranslate">Exception</code>. </dd> </dl> </li> <li><dl> <dt><code class="docutils literal notranslate">InterpreterNotFoundError</code></dt><dd>Raised from <code class="docutils literal notranslate">Interpreter</code> methods after the underlying interpreter has been destroyed, e.g. via the C-API.This exception is a subclass of <code class="docutils literal notranslate">InterpreterError</code>. </dd> </dl> </li> <li><dl> <dt><code class="docutils literal notranslate">ExecutionFailed</code></dt><dd>Raised from <code class="docutils literal notranslate">Interpreter.exec()</code> and <code class="docutils literal notranslate">Interpreter.call()</code> when there’s an uncaught exception. The error display for this exception includes the traceback of the uncaught exception, which gets shown after the normal error display, much like happens for <code class="docutils literal notranslate">ExceptionGroup</code>.Attributes: <ul class="simple"> <li><code class="docutils literal notranslate">type</code> - a representation of the original exception’s class, with <code class="docutils literal notranslate">__name__</code>, <code class="docutils literal notranslate">__module__</code>, and <code class="docutils literal notranslate">__qualname__</code> attrs.</li> <li><code class="docutils literal notranslate">msg</code> - <code class="docutils literal notranslate">str(exc)</code> of the original exception</li> <li><code class="docutils literal notranslate">snapshot</code> - a <code class="docutils literal notranslate">traceback.TracebackException</code> object for the original exception</li> </ul> This exception is a subclass of <code class="docutils literal notranslate">InterpreterError</code>. </dd> </dl> </li> <li><dl> <dt><code class="docutils literal notranslate">QueueError</code></dt><dd>Indicates that some queue-related failure occurred.This exception is a subclass of <code class="docutils literal notranslate">Exception</code>. </dd> </dl> </li> <li><dl> <dt><code class="docutils literal notranslate">QueueNotFoundError</code></dt><dd>Raised from <code class="docutils literal notranslate">interpreters.Queue</code> methods after the underlying queue has been destroyed.This exception is a subclass of <code class="docutils literal notranslate">QueueError</code>. </dd> </dl> </li> <li><dl> <dt><code class="docutils literal notranslate">QueueEmpty</code></dt><dd>Raised from <code class="docutils literal notranslate">Queue.get()</code> (or <code class="docutils literal notranslate">get_nowait()</code> with no default) when the queue is empty.This exception is a subclass of both <code class="docutils literal notranslate">QueueError</code> and the stdlib <code class="docutils literal notranslate">queue.Empty</code>. </dd> </dl> </li> <li><dl> <dt><code class="docutils literal notranslate">QueueFull</code></dt><dd>Raised from <code class="docutils literal notranslate">Queue.put()</code> (with a timeout) or <code class="docutils literal notranslate">put_nowait()</code> when the queue is already at its max size.This exception is a subclass of both <code class="docutils literal notranslate">QueueError</code> and the stdlib <code class="docutils literal notranslate">queue.Empty</code>. </dd> </dl> </li> </ul> </section> <section id="interpreterpoolexecutor"> <h3><a class="toc-backref" href="#interpreterpoolexecutor" role="doc-backlink">InterpreterPoolExecutor</a></h3> Along with the new <code class="docutils literal notranslate">interpreters</code> module, there will be a new <code class="docutils literal notranslate">concurrent.futures.InterpreterPoolExecutor</code>. It will be a derivative of <code class="docutils literal notranslate">ThreadPoolExecutor</code>, where each worker executes in its own thread, but each with its own subinterpreter. Like the other executors, <code class="docutils literal notranslate">InterpreterPoolExecutor</code> will support callables for tasks, and for the initializer. Also like the other executors, the arguments in both cases will be mostly unrestricted. The callables and arguments will typically be serialized when sent to a worker’s interpreter, e.g. with pickle, like how the <code class="docutils literal notranslate">ProcessPoolExecutor</code> works. This contrasts with <code class="docutils literal notranslate">Interpreter.call()</code>, which will (at least initially) be much more restricted. Communication between workers, or between the executor (or generally its interpreter) and the workers, may still be done through <code class="docutils literal notranslate">interpreters.Queue</code> objects, set with the initializer. </section> <section id="sys-implementation-supports-isolated-interpreters"> <h3><a class="toc-backref" href="#sys-implementation-supports-isolated-interpreters" role="doc-backlink">sys.implementation.supports_isolated_interpreters</a></h3> Python implementations are not required to support subinterpreters, though most major ones do. If an implementation does support them then <code class="docutils literal notranslate">sys.implementation.supports_isolated_interpreters</code> will be set to <code class="docutils literal notranslate">True</code>. Otherwise it will be <code class="docutils literal notranslate">False</code>. If the feature is not supported then importing the <code class="docutils literal notranslate">interpreters</code> module will raise an <code class="docutils literal notranslate">ImportError</code>. </section> <section id="examples"> <h3><a class="toc-backref" href="#examples" role="doc-backlink">Examples</a></h3> The following examples demonstrate practical cases where multiple interpreters may be useful. Example 1: There’s a stream of requests coming in that will be handled via workers in sub-threads. <ul class="simple"> <li>each worker thread has its own interpreter</li> <li>there’s one queue to send tasks to workers and another queue to return results</li> <li>the results are handled in a dedicated thread</li> <li>each worker keeps going until it receives a “stop” sentinel (<code class="docutils literal notranslate">None</code>)</li> <li>the results handler keeps going until all workers have stopped</li> </ul> <div class="highlight-default notranslate"><div class="highlight"><pre>import interpreters from mymodule import iter_requests, handle_result tasks = interpreters.create_queue() results = interpreters.create_queue() numworkers = 20 threads = [] def results_handler(): running = numworkers while running: try: res = results.get(timeout=0.1) except interpreters.QueueEmpty: # No workers have finished a request since last time. pass else: if res is None: # A worker has stopped. running -= 1 else: handle_result(res) empty = object() assert results.get_nowait(empty) is empty threads.append(threading.Thread(target=results_handler)) def worker(): interp = interpreters.create() interp.prepare_main(tasks=tasks, results=results) interp.exec("""if True: from mymodule import handle_request, capture_exception while True: req = tasks.get() if req is None: # Stop! break try: res = handle_request(req) except Exception as exc: res = capture_exception(exc) results.put(res) # Notify the results handler. results.put(None) """) threads.extend(threading.Thread(target=worker) for _ in range(numworkers)) for t in threads: t.start() for req in iter_requests(): tasks.put(req) # Send the "stop" signal. for _ in range(numworkers): tasks.put(None) for t in threads: t.join() </pre></div> </div> Example 2: This case is similar to the last as there are a bunch of workers in sub-threads. However, this time the code is chunking up a big array of data, where each worker processes one chunk at a time. Copying that data to each interpreter would be exceptionally inefficient, so the code takes advantage of directly sharing <code class="docutils literal notranslate">memoryview</code> buffers. <ul class="simple"> <li>all the interpreters share the buffer of the source array</li> <li>each one writes its results to a second shared buffer</li> <li>there’s use a queue to send tasks to workers</li> <li>only one worker will ever read any given index in the source array</li> <li>only one worker will ever write to any given index in the results (this is how it ensures thread-safety)</li> </ul> <div class="highlight-default notranslate"><div class="highlight"><pre>import interpreters import queue from mymodule import read_large_data_set, use_results numworkers = 3 data, chunksize = read_large_data_set() buf = memoryview(data) numchunks = (len(buf) + 1) / chunksize results = memoryview(b'\0' * numchunks) tasks = interpreters.create_queue() def worker(id): interp = interpreters.create() interp.prepare_main(data=buf, results=results, tasks=tasks) interp.exec("""if True: from mymodule import reduce_chunk while True: req = tasks.get() if res is None: # Stop! break resindex, start, end = req chunk = data[start: end] res = reduce_chunk(chunk) results[resindex] = res """) threads = [threading.Thread(target=worker) for _ in range(numworkers)] for t in threads: t.start() for i in range(numchunks): # Assume there's at least one worker running still. start = i * chunksize end = start + chunksize if end > len(buf): end = len(buf) tasks.put((start, end, i)) # Send the "stop" signal. for _ in range(numworkers): tasks.put(None) for t in threads: t.join() use_results(results) </pre></div> </div> </section> </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> <section id="a-minimal-api"> <h3><a class="toc-backref" href="#a-minimal-api" role="doc-backlink">A Minimal API</a></h3> Since the core dev team has no real experience with how users will make use of multiple interpreters in Python code, this proposal purposefully keeps the initial API as lean and minimal as possible. The objective is to provide a well-considered foundation on which further (more advanced) functionality may be added later, as appropriate. That said, the proposed design incorporates lessons learned from existing use of subinterpreters by the community, from existing stdlib modules, and from other programming languages. It also factors in experience from using subinterpreters in the CPython test suite and using them in <a class="reference external" href="https://github.com/ericsnowcurrently/concurrency-benchmarks">concurrency benchmarks</a>. </section> <section id="create-create-queue"> <h3><a class="toc-backref" href="#create-create-queue" role="doc-backlink">create(), create_queue()</a></h3> Typically, users call a type to create instances of the type, at which point the object’s resources get provisioned. The <code class="docutils literal notranslate">interpreters</code> module takes a different approach, where users must call <code class="docutils literal notranslate">create()</code> to get a new interpreter or <code class="docutils literal notranslate">create_queue()</code> for a new queue. Calling <code class="docutils literal notranslate">interpreters.Interpreter()</code> directly only returns a wrapper around an existing interpreters (likewise for <code class="docutils literal notranslate">interpreters.Queue()</code>). This is because interpreters (and queues) are special resources. They exist globally in the process and are not managed/owned by the current interpreter. Thus the <code class="docutils literal notranslate">interpreters</code> module makes creating an interpreter (or queue) a visibly distinct operation from creating an instance of <code class="docutils literal notranslate">interpreters.Interpreter</code> (or <code class="docutils literal notranslate">interpreters.Queue</code>). </section> <section id="interpreter-prepare-main-sets-multiple-variables"> <h3><a class="toc-backref" href="#interpreter-prepare-main-sets-multiple-variables" role="doc-backlink">Interpreter.prepare_main() Sets Multiple Variables</a></h3> <code class="docutils literal notranslate">prepare_main()</code> may be seen as a setter function of sorts. It supports setting multiple names at once, e.g. <code class="docutils literal notranslate">interp.prepare_main(spam=1, eggs=2)</code>, whereas most setters set one item at a time. The main reason is for efficiency. To set a value in the interpreter’s <code class="docutils literal notranslate">__main__.__dict__</code>, the implementation must first switch the OS thread to the identified interpreter, which involves some non-negligible overhead. After setting the value it must switch back. Furthermore, there is some additional overhead to the mechanism by which it passes objects between interpreters, which can be reduced in aggregate if multiple values are set at once. Therefore, <code class="docutils literal notranslate">prepare_main()</code> supports setting multiple values at once. </section> <section id="propagating-exceptions"> <h3><a class="toc-backref" href="#propagating-exceptions" role="doc-backlink">Propagating Exceptions</a></h3> An uncaught exception from a subinterpreter, via <code class="docutils literal notranslate">Interpreter.exec()</code>, could either be (effectively) ignored, like <code class="docutils literal notranslate">threading.Thread()</code> does, or propagated, like the builtin <code class="docutils literal notranslate">exec()</code> does. Since <code class="docutils literal notranslate">Interpreter.exec()</code> is a synchronous operation, like the builtin <code class="docutils literal notranslate">exec()</code>, uncaught exceptions are propagated. However, such exceptions are not raised directly. That’s because interpreters are isolated from each other and must not share objects, including exceptions. That could be addressed by raising a surrogate of the exception, whether a summary, a copy, or a proxy that wraps it. Any of those could preserve the traceback, which is useful for debugging. The <code class="docutils literal notranslate">ExecutionFailed</code> that gets raised is such a surrogate. There’s another concern to consider. If a propagated exception isn’t immediately caught, it will bubble up through the call stack until caught (or not). In the case that code somewhere else may catch it, it is helpful to identify that the exception came from a subinterpreter (i.e. a “remote” source), rather than from the current interpreter. That’s why <code class="docutils literal notranslate">Interpreter.exec()</code> raises <code class="docutils literal notranslate">ExecutionFailed</code> and why it is a plain <code class="docutils literal notranslate">Exception</code>, rather than a copy or proxy with a class that matches the original exception. For example, an uncaught <code class="docutils literal notranslate">ValueError</code> from a subinterpreter would never get caught in a later <code class="docutils literal notranslate">try: ... except ValueError: ...</code>. Instead, <code class="docutils literal notranslate">ExecutionFailed</code> must be handled directly. In contrast, exceptions propagated from <code class="docutils literal notranslate">Interpreter.call()</code> do not involve <code class="docutils literal notranslate">ExecutionFailed</code> but are raised directly, as though originating in the calling interpreter. This is because <code class="docutils literal notranslate">Interpreter.call()</code> is a higher level method that uses pickle to support objects that can’t normally be passed between interpreters. </section> <section id="limited-object-sharing"> <h3><a class="toc-backref" href="#limited-object-sharing" role="doc-backlink">Limited Object Sharing</a></h3> As noted in <a class="reference internal" href="#interpreter-isolation">Interpreter Isolation</a>, only a small number of builtin objects may be truly shared between interpreters. In all other cases objects can only be shared indirectly, through copies or proxies. The set of objects that are shareable as copies through queues (and <code class="docutils literal notranslate">Interpreter.prepare_main()</code>) is limited for the sake of efficiency. Supporting sharing of all objects is possible (via pickle) but not part of this proposal. For one thing, it’s helpful to know in those cases that only an efficient implementation is being used. Furthermore, in those cases supporting mutable objects via pickling would violate the guarantee that “shared” objects be equivalent (and stay that way). </section> <section id="objects-vs-id-proxies"> <h3><a class="toc-backref" href="#objects-vs-id-proxies" role="doc-backlink">Objects vs. ID Proxies</a></h3> For both interpreters and queues, the low-level module makes use of proxy objects that expose the underlying state by their corresponding process-global IDs. In both cases the state is likewise process-global and will be used by multiple interpreters. Thus they aren’t suitable to be implemented as <code class="docutils literal notranslate">PyObject</code>, which is only really an option for interpreter-specific data. That’s why the <code class="docutils literal notranslate">interpreters</code> module instead provides objects that are weakly associated through the ID. </section> </section> <section id="rejected-ideas"> <h2><a class="toc-backref" href="#rejected-ideas" role="doc-backlink">Rejected Ideas</a></h2> See <a class="pep reference internal" href="../pep-0554/#rejected-ideas" title="PEP 554 – Multiple Interpreters in the Stdlib § Rejected Ideas">PEP 554</a>. </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0734.rst">https://github.com/python/peps/blob/main/peps/pep-0734.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0734.rst">2024-04-10 21:49:06 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#introduction">Introduction</a><ul> <li><a class="reference internal" href="#threads-and-thread-states">Threads and Thread States</a></li> <li><a class="reference internal" href="#interpreter-states">Interpreter States</a></li> <li><a class="reference internal" href="#interpreters-and-threads">Interpreters and Threads</a></li> <li><a class="reference internal" href="#the-main-interpreter">The “Main” Interpreter</a></li> <li><a class="reference internal" href="#interpreter-isolation">Interpreter Isolation</a></li> <li><a class="reference internal" href="#existing-execution-components">Existing Execution Components</a><ul> <li><a class="reference internal" href="#builtins-exec">builtins.exec()</a></li> <li><a class="reference internal" href="#command-line">Command-line</a></li> <li><a class="reference internal" href="#threading-thread">threading.Thread</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#motivation">Motivation</a></li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#using-interpreters">Using Interpreters</a></li> <li><a class="reference internal" href="#interpreter-objects">Interpreter Objects</a></li> <li><a class="reference internal" href="#communicating-between-interpreters">Communicating Between Interpreters</a></li> <li><a class="reference internal" href="#queue-objects">Queue Objects</a></li> <li><a class="reference internal" href="#shareable-objects">Shareable Objects</a></li> <li><a class="reference internal" href="#synchronization">Synchronization</a></li> <li><a class="reference internal" href="#exceptions">Exceptions</a></li> <li><a class="reference internal" href="#interpreterpoolexecutor">InterpreterPoolExecutor</a></li> <li><a class="reference internal" href="#sys-implementation-supports-isolated-interpreters">sys.implementation.supports_isolated_interpreters</a></li> <li><a class="reference internal" href="#examples">Examples</a></li> </ul> </li> <li><a class="reference internal" href="#rationale">Rationale</a><ul> <li><a class="reference internal" href="#a-minimal-api">A Minimal API</a></li> <li><a class="reference internal" href="#create-create-queue">create(), create_queue()</a></li> <li><a class="reference internal" href="#interpreter-prepare-main-sets-multiple-variables">Interpreter.prepare_main() Sets Multiple Variables</a></li> <li><a class="reference internal" href="#propagating-exceptions">Propagating Exceptions</a></li> <li><a class="reference internal" href="#limited-object-sharing">Limited Object Sharing</a></li> <li><a class="reference internal" href="#objects-vs-id-proxies">Objects vs. ID Proxies</a></li> </ul> </li> <li><a class="reference internal" href="#rejected-ideas">Rejected Ideas</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0734.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>