Skip to content

[3.14] gh-134939: Fill Out the concurrent.interpreters Docs (gh-135902) #136141

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 30, 2025
+206 −17
Merged

[3.14] gh-134939: Fill Out the concurrent.interpreters Docs (gh-135902) #136141

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
223 changes: 206 additions & 17 deletions Doc/library/concurrent.interpreters.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,17 +13,26 @@

--------------


Introduction
------------

The :mod:`!concurrent.interpreters` module constructs higher-level
interfaces on top of the lower level :mod:`!_interpreters` module.

.. XXX Add references to the upcoming HOWTO docs in the seealso block.
The module is primarily meant to provide a basic API for managing
interpreters (AKA "subinterpreters") and running things in them.
Running mostly involves switching to an interpreter (in the current
thread) and calling a function in that execution context.

For concurrency, interpreters themselves (and this module) don't
provide much more than isolation, which on its own isn't useful.
Actual concurrency is available separately through
:mod:`threads <threading>` See `below <interp-concurrency_>`_

.. seealso::

:class:`~concurrent.futures.InterpreterPoolExecutor`
combines threads with interpreters in a familiar interface.

.. XXX Add references to the upcoming HOWTO docs in the seealso block.
:ref:`isolating-extensions-howto`
how to update an extension module to support multiple interpreters

Expand All @@ -41,18 +50,155 @@ interfaces on top of the lower level :mod:`!_interpreters` module.
Key details
-----------

Before we dive into examples, there are a small number of details
Before we dive in further, there are a small number of details
to keep in mind about using multiple interpreters:

* isolated, by default
* `isolated <interp-isolation_>`_, by default
* no implicit threads
* not all PyPI packages support use in multiple interpreters yet

.. XXX Are there other relevant details to list?
In the context of multiple interpreters, "isolated" means that
different interpreters do not share any state. In practice, there is some
process-global data they all share, but that is managed by the runtime.
.. _interpreters-intro:

Introduction
------------

An "interpreter" is effectively the execution context of the Python
runtime. It contains all of the state the runtime needs to execute
a program. This includes things like the import state and builtins.
(Each thread, even if there's only the main thread, has some extra
runtime state, in addition to the current interpreter, related to
the current exception and the bytecode eval loop.)

The concept and functionality of the interpreter have been a part of
Python since version 2.2, but the feature was only available through
the C-API and not well known, and the `isolation <interp-isolation_>`_
was relatively incomplete until version 3.12.

.. _interp-isolation:

Multiple Interpreters and Isolation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A Python implementation may support using multiple interpreters in the
same process. CPython has this support. Each interpreter is
effectively isolated from the others (with a limited number of
carefully managed process-global exceptions to the rule).

That isolation is primarily useful as a strong separation between
distinct logical components of a program, where you want to have
careful control of how those components interact.

.. note::

Interpreters in the same process can technically never be strictly
isolated from one another since there are few restrictions on memory
access within the same process. The Python runtime makes a best
effort at isolation but extension modules may easily violate that.
Therefore, do not use multiple interpreters in security-sensitive
situations, where they shouldn't have access to each other's data.

Running in an Interpreter
^^^^^^^^^^^^^^^^^^^^^^^^^

Running in a different interpreter involves switching to it in the
current thread and then calling some function. The runtime will
execute the function using the current interpreter's state. The
:mod:`!concurrent.interpreters` module provides a basic API for
creating and managing interpreters, as well as the switch-and-call
operation.

No other threads are automatically started for the operation.
There is `a helper <interp-call-in-thread_>`_ for that though.
There is another dedicated helper for calling the builtin
:func:`exec` in an interpreter.

When :func:`exec` (or :func:`eval`) are called in an interpreter,
they run using the interpreter's :mod:`!__main__` module as the
"globals" namespace. The same is true for functions that aren't
associated with any module. This is the same as how scripts invoked
from the command-line run in the :mod:`!__main__` module.


.. _interp-concurrency:

Concurrency and Parallelism
^^^^^^^^^^^^^^^^^^^^^^^^^^^

As noted earlier, interpreters do not provide any concurrency
on their own. They strictly represent the isolated execution
context the runtime will use *in the current thread*. That isolation
makes them similar to processes, but they still enjoy in-process
efficiency, like threads.

All that said, interpreters do naturally support certain flavors of
concurrency, as a powerful side effect of that isolation.
There's a powerful side effect of that isolation. It enables a
different approach to concurrency than you can take with async or
threads. It's a similar concurrency model to CSP or the actor model,
a model which is relatively easy to reason about.

You can take advantage of that concurrency model in a single thread,
switching back and forth between interpreters, Stackless-style.
However, this model is more useful when you combine interpreters
with multiple threads. This mostly involves starting a new thread,
where you switch to another interpreter and run what you want there.

Each actual thread in Python, even if you're only running in the main
thread, has its own *current* execution context. Multiple threads can
use the same interpreter or different ones.

At a high level, you can think of the combination of threads and
interpreters as threads with opt-in sharing.

As a significant bonus, interpreters are sufficiently isolated that
they do not share the :term:`GIL`, which means combining threads with
multiple interpreters enables full multi-core parallelism.
(This has been the case since Python 3.12.)

Communication Between Interpreters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In practice, multiple interpreters are useful only if we have a way
to communicate between them. This usually involves some form of
message passing, but can even mean sharing data in some carefully
managed way.

With this in mind, the :mod:`!concurrent.interpreters` module provides
a :class:`queue.Queue` implementation, available through
:func:`create_queue`.

.. _interp-object-sharing:

"Sharing" Objects
^^^^^^^^^^^^^^^^^

Any data actually shared between interpreters loses the thread-safety
provided by the :term:`GIL`. There are various options for dealing with
this in extension modules. However, from Python code the lack of
thread-safety means objects can't actually be shared, with a few
exceptions. Instead, a copy must be created, which means mutable
objects won't stay in sync.

By default, most objects are copied with :mod:`pickle` when they are
passed to another interpreter. Nearly all of the immutable builtin
objects are either directly shared or copied efficiently. For example:

* :const:`None`
* :class:`bool` (:const:`True` and :const:`False`)
* :class:`bytes`
* :class:`str`
* :class:`int`
* :class:`float`
* :class:`tuple` (of similarly supported objects)

There is a small number of Python types that actually share mutable
data between interpreters:

* :class:`memoryview`
* :class:`Queue`


Reference
Expand All @@ -73,12 +219,19 @@ This module defines the following functions:
.. function:: get_main()

Return an :class:`Interpreter` object for the main interpreter.
This is the interpreter the runtime created to run the :term:`REPL`
or the script given at the command-line. It is usually the only one.

.. function:: create()

Initialize a new (idle) Python interpreter
and return a :class:`Interpreter` object for it.

.. function:: create_queue()

Initialize a new cross-interpreter queue and return a :class:`Queue`
object for it.


Interpreter objects
^^^^^^^^^^^^^^^^^^^
Expand All @@ -94,7 +247,7 @@ Interpreter objects

(read-only)

The interpreter's ID.
The underlying interpreter's ID.

.. attribute:: whence

Expand All @@ -113,8 +266,10 @@ Interpreter objects

.. method:: prepare_main(ns=None, **kwargs)

Bind "shareable" objects in the interpreter's
:mod:`!__main__` module.
Bind objects in the interpreter's :mod:`!__main__` module.

Some objects are actually shared and some are copied efficiently,
but most are copied via :mod:`pickle`. See :ref:`interp-object-sharing`.

.. method:: exec(code, /, dedent=True)

Expand All @@ -125,6 +280,8 @@ Interpreter objects
Return the result of calling running the given function in the
interpreter (in the current thread).

.. _interp-call-in-thread:

.. method:: call_in_thread(callable, /, *args, **kwargs)

Run the given function in the interpreter (in a new thread).
Expand Down Expand Up @@ -159,7 +316,36 @@ Exceptions
an object cannot be sent to another interpreter.


.. XXX Add functions for communicating between interpreters.
Communicating Between Interpreters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. class:: Queue(id)

A wrapper around a low-level, cross-interpreter queue, which
implements the :class:`queue.Queue` interface. The underlying queue
can only be created through :func:`create_queue`.

Some objects are actually shared and some are copied efficiently,
but most are copied via :mod:`pickle`. See :ref:`interp-object-sharing`.

.. attribute:: id

(read-only)

The queue's ID.


.. exception:: QueueEmptyError

This exception, a subclass of :exc:`queue.Empty`, is raised from
:meth:`!Queue.get` and :meth:`!Queue.get_nowait` when the queue
is empty.

.. exception:: QueueFullError

This exception, a subclass of :exc:`queue.Full`, is raised from
:meth:`!Queue.put` and :meth:`!Queue.put_nowait` when the queue
is full.


Basic usage
Expand All @@ -184,6 +370,12 @@ Creating an interpreter and running code in it::
print('spam!')
"""))

def run(arg):
return arg

res = interp.call(run, 'spam!')
print(res)

def run():
print('spam!')

Expand All @@ -193,6 +385,3 @@ Creating an interpreter and running code in it::

t = interp.call_in_thread(run)
t.join()


.. XXX Explain about object "sharing".
Loading