python · ericsnowcurrently · Oct 16, 2024 · Sep 25, 2024 · Sep 25, 2024 · Sep 27, 2024
@@ -103,7 +103,8 @@ To handle signals the event loop must be
 run in the main thread.
 
 The :meth:`loop.run_in_executor` method can be used with a
-:class:`concurrent.futures.ThreadPoolExecutor` to execute
+:class:`concurrent.futures.ThreadPoolExecutor` or
+:class:`~concurrent.futures.InterpreterPoolExecutor` to execute
 blocking code in a different OS thread without blocking the OS thread
 that the event loop runs in.
 
@@ -128,7 +129,8 @@ if a function performs a CPU-intensive calculation for 1 second,
 all concurrent asyncio Tasks and IO operations would be delayed
 by 1 second.
 
-An executor can be used to run a task in a different thread or even in
+An executor can be used to run a task in a different thread,
+including in a different interpreter, or even in
 a different process to avoid blocking the OS thread with the
 event loop.  See the :meth:`loop.run_in_executor` method for more
 details.

@@ -1305,6 +1305,12 @@ Executing code in thread or process pools
                   pool, cpu_bound)
               print('custom process pool', result)
 
+          # 4. Run in a custom interpreter pool:
+          with concurrent.futures.InterpreterPoolExecutor() as pool:
+              result = await loop.run_in_executor(
+                  pool, cpu_bound)
+              print('custom interpreter pool', result)
+
       if __name__ == '__main__':
           asyncio.run(main())
 
@@ -1329,7 +1335,8 @@ Executing code in thread or process pools
 
    Set *executor* as the default executor used by :meth:`run_in_executor`.
    *executor* must be an instance of
-   :class:`~concurrent.futures.ThreadPoolExecutor`.
+   :class:`~concurrent.futures.ThreadPoolExecutor`, which includes
+   :class:`~concurrent.futures.InterpreterPoolExecutor`.
 
    .. versionchanged:: 3.11
       *executor* must be an instance of

@@ -96,7 +96,7 @@ See also the main documentation section about the
       - Invoke a callback *at* the given time.
 
 
-.. rubric:: Thread/Process Pool
+.. rubric:: Thread/Interpreter/Process Pool
 .. list-table::
     :widths: 50 50
     :class: full-width-table

diff --git a/Doc/library/concurrent.futures.rst b/Doc/library/concurrent.futures.rst
@@ -15,9 +15,10 @@ The :mod:`concurrent.futures` module provides a high-level interface for
 asynchronously executing callables.
 
 The asynchronous execution can be performed with threads, using
-:class:`ThreadPoolExecutor`, or separate processes, using
-:class:`ProcessPoolExecutor`.  Both implement the same interface, which is
-defined by the abstract :class:`Executor` class.
+:class:`ThreadPoolExecutor` or :class:`InterpreterPoolExecutor`,
+or separate processes, using :class:`ProcessPoolExecutor`.
+Each implements the same interface, which is defined
+by the abstract :class:`Executor` class.
 
 .. include:: ../includes/wasm-notavail.rst
 
@@ -63,7 +64,8 @@ Executor Objects
       setting *chunksize* to a positive integer.  For very long iterables,
       using a large value for *chunksize* can significantly improve
       performance compared to the default size of 1.  With
-      :class:`ThreadPoolExecutor`, *chunksize* has no effect.
+      :class:`ThreadPoolExecutor` and :class:`InterpreterPoolExecutor`,
+      *chunksize* has no effect.
 
       .. versionchanged:: 3.5
          Added the *chunksize* argument.
@@ -227,6 +229,59 @@ ThreadPoolExecutor Example
                print('%r page is %d bytes' % (url, len(data)))
 
 
+InterpreterPoolExecutor
+-----------------------
+
+The :class:`InterpreterPoolExecutor` class, a :class:`ThreadPoolExecutor`
+subclass, uses a pool of isolated interpreters to execute calls
+asynchronously.  Since each interpreter is isolated from the others,
+side-stepping the :term:`Global Interpreter Lock <global interpreter lock>` ,
+multiple cores can be used.  Since Interpreters do not share
+objects between them, in most cases, only picklable
+objects can be executed and returned.
+
+.. class:: InterpreterPoolExecutor(max_workers=None, thread_name_prefix='', initializer=None, initargs=(), shared=None)
+
+   A :class:`ThreadPoolExecutor` subclass that executes calls asynchronously
+   using a pool of at most *max_workers* threads.  Each thread runs
+   tasks in its own interpreter.
+
+   *initializer* may be a callable and *initargs* a tuple of arguments,
+   just like with :class:`ThreadPoolExecutor`.  However, they are pickled
+   like with :class:`ProcessPoolExecutor`.  Likewise, functions (and
+   arguments) passed to :meth:`~Executor.submit` are pickled.
-   *initializer* may be a callable and *initargs* a tuple of arguments,
-   just like with :class:`ThreadPoolExecutor`.  However, they are pickled
-   like with :class:`ProcessPoolExecutor`.  Likewise, functions (and
-   arguments) passed to :meth:`~Executor.submit` are pickled.
+   An *initializer* may be a callable and *initargs* a tuple of arguments,
+   similar to the behavior of :class:`ThreadPoolExecutor`.  Additionally, they are pickled
+   like with :class:`ProcessPoolExecutor`.  Likewise, functions (and
+   arguments) passed to :meth:`~Executor.submit` are pickled.
-   *initializer* may be a callable and *initargs* a tuple of arguments,
-   just like with :class:`ThreadPoolExecutor`.  However, they are pickled
-   like with :class:`ProcessPoolExecutor`.  Likewise, functions (and
-   arguments) passed to :meth:`~Executor.submit` are pickled.
+   An *initializer* may be a callable and *initargs* a tuple of arguments,
+   similar to the behavior of :class:`ThreadPoolExecutor`.  Additionally, they are pickled
+   like with :class:`ProcessPoolExecutor`.  Likewise, functions (and
+   arguments) passed to :meth:`~Executor.submit` are pickled.
+
+   .. note::
+      functions defined in the ``__main__`` module cannot be pickled
+      and thus cannot be used.
+
+   *shared* is an optional dict of objects shared by all interpreters
+   in the pool.  The items are added to each interpreter's ``__main__``
+   module.  Not all objects are shareable.  Those that are include
+   the builtin singletons, :class:`str` and :class:`bytes`,
+   and :class:`memoryview`.  See :pep:`734` for more info.
-   *shared* is an optional dict of objects shared by all interpreters
-   in the pool.  The items are added to each interpreter's ``__main__``
-   module.  Not all objects are shareable.  Those that are include
-   the builtin singletons, :class:`str` and :class:`bytes`,
-   and :class:`memoryview`.  See :pep:`734` for more info.
+   *shared* is an optional dict of objects shared by all isolated interpreters
+   in the pool.  The *shared* items are added to each interpreter's ``__main__``
+   module.  Not all objects are shareable.  Shareable objects include
+   the builtin singletons, :class:`str` and :class:`bytes`,
+   and :class:`memoryview`.  See :pep:`734` for more info.
-   *shared* is an optional dict of objects shared by all interpreters
-   in the pool.  The items are added to each interpreter's ``__main__``
-   module.  Not all objects are shareable.  Those that are include
-   the builtin singletons, :class:`str` and :class:`bytes`,
-   and :class:`memoryview`.  See :pep:`734` for more info.
+   *shared* is an optional dict of objects shared by all isolated interpreters
+   in the pool.  The *shared* items are added to each interpreter's ``__main__``
+   module.  Not all objects are shareable.  Shareable objects include
+   the builtin singletons, :class:`str` and :class:`bytes`,
+   and :class:`memoryview`.  See :pep:`734` for more info.
+
+   You can also pass a script (:class:`str`) for *initializer* or to
+   :meth:`~Executor.submit` (but not to :meth:`~Executor.map`).
+   In both cases, the script will be executed in the interpreter's
+   ``__main__`` module.  The executor will automatically apply
+   :func:`textwrap.dedent` to the script, so you don't have to do so.
+   With a script, arguments must not be passed in.
+   For :meth:`!Executor.submit`, the return value for a script
+   is always ``None``.
+
+   Normally an uncaught exception from *initializer* or from a submitted
+   task will be sent back to be raised as is.
+   However, in some situations the exception might not be suitable to be
+   sent back.  In that case, the executor raises an
+   :class:`~concurrent.futures.interpreter.ExecutionFailed` exception
+   instead, which contains a summary of the original exception.
+
+   Other caveats from parent :class:`ThreadPoolExecutor` apply here.
+
+   .. versionadded:: next
+
+
 ProcessPoolExecutor
 -------------------
 
@@ -574,6 +629,26 @@ Exception classes
 
    .. versionadded:: 3.7
 
+.. currentmodule:: concurrent.futures.interpreter
+
+.. exception:: BrokenInterpreterPool
+
+   Derived from :exc:`~concurrent.futures.thread.BrokenThreadPool`,
+   this exception class is raised when one of the workers
+   of a :class:`~concurrent.futures.InterpreterPoolExecutor`
+   has failed initializing.
+
+   .. versionadded:: next
+
+.. exception:: ExecutionFailed
+
+   Raised from :class:`~concurrent.futures.InterpreterPoolExecutor` when
+   the given initializer fails or from
+   :meth:`~concurrent.futures.Executor.submit` when there's an uncaught
+   exception from the submitted task.
+
+   .. versionadded:: next
+
 .. currentmodule:: concurrent.futures.process
 
 .. exception:: BrokenProcessPool

@@ -225,6 +225,14 @@ ast
 * The ``repr()`` output for AST nodes now includes more information.
   (Contributed by Tomas R in :gh:`116022`.)
 
+concurrent.futures
+------------------
+
+* Add :class:`~concurrent.futures.InterpreterPoolExecutor`,
+  which exposes "subinterpreters (multiple Python interpreters in the
+  same process) to Python code.  This is separate from the proposed API
+  in :pep:`734`.
+  (Contributed by Eric Snow in :gh:`124548`.)
 
 ctypes
 ------

diff --git a/Lib/concurrent/futures/__init__.py b/Lib/concurrent/futures/__init__.py
@@ -29,6 +29,7 @@
     'Executor',
     'wait',
     'as_completed',
+    'InterpreterPoolExecutor',
     'ProcessPoolExecutor',
     'ThreadPoolExecutor',
 )
@@ -39,7 +40,7 @@ def __dir__():
 
 
 def __getattr__(name):
-    global ProcessPoolExecutor, ThreadPoolExecutor
+    global ProcessPoolExecutor, ThreadPoolExecutor, InterpreterPoolExecutor
 
     if name == 'ProcessPoolExecutor':
         from .process import ProcessPoolExecutor as pe
@@ -51,4 +52,13 @@ def __getattr__(name):
         ThreadPoolExecutor = te
         return te
 
+    if name == 'InterpreterPoolExecutor':
+        try:
+            from .interpreter import InterpreterPoolExecutor as ie
+        except ModuleNotFoundError:
+            ie = InterpreterPoolExecutor = None
+        else:
+            InterpreterPoolExecutor = ie
+        return ie
+
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")