@@ -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.

.. seealso::

   :ref:`isolating-extensions-howto`
       how to update an extension module to support multiple interpreters

@@ -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
to keep in mind about using multiple interpreters:

-* isolated, 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.


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

   Return an :class:`Interpreter` object for the main interpreter.

.. function:: create()

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


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

      (read-only)

-      The interpreter's ID.

   .. attribute:: whence

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

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

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

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

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

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

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


-.. XXX Add functions for communicating between interpreters.


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

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

@@ -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".