Jul 16, 2024 · Jun 19, 2025 · Jun 20, 2025 · Jun 26, 2025 · Jun 30, 2025 · Jun 30, 2025
diff --git a/Doc/howto/multiple-interpreters.rst b/Doc/howto/multiple-interpreters.rst
 Calling a Function in an Interpreter
 ------------------------------------

 You can just as easily call a function in another interpreter::
 You can just as easily*call* a function in another interpreter::

    from concurrent import interpreters

        interp.call(spam)
        # prints: spam!

 In fact, nearly all Python functions and callables are supported,
 with the notable exception of closures.  Support includes arguments
 and return values, which we'll
 :ref:`explore soon <interp-tutorial-return-values>`.
 (See :meth:`Interpreter.call`.)

 Builtin functions always execute in the target interpreter's
 :mod:`!__main__` module::
 In fact, nearly all Python functions and callables are supported, with
 the notable exclusion of closures.  We'll focus on plain functions
 for the moment.

 Relative to :meth:`Interpreter.call`, there are five kinds of functions:

 1. builtin functions
 2. extension module functions
 3. "stateless" user functions
 4. stateful user functions, defined in :mod:`!__main__`
 5. stateful user functions, not defined in :mod:`!__main__`

 A "stateless" function is one that doesn't use any globals.  It also
 can't be a closure.  It can have parameters but not argument defaults.
 It can have return values.  We'll cover
 :ref:`arguments and returning <interp-tutorial-return-values>` soon.

 Some builtin functions, like :func:`exec` and :func:`eval`, use the
 current globals as a default (or :func:`implicit <globals>`) argument
 value.  When such functions are called directly with
 :meth:`Interpreter.call`, they use the :mod:`!__main__` module's
 :data:`!__dict__` as the default/implicit "globals"::

    from concurrent import interpreters

    interp.call(eval, 'print(__name__)')
    # prints: __main__

 The same is true for Python functions that don't use any globals::
 Note that, for some of those builtin functions, like :func:`globals`
 and even :func:`eval` (for some expressions), the return value may
 be :ref:`"unshareable" <interp-tutorial-shareable>` and the call will
 fail.

    from concurrent import interpreters
 In each of the above cases, the function is more-or-less copied, when
 sent to the other interpreter.  For most of the cases, the function's
 module is imported in the target interpreter and the function is pulled
 from there.  The exceptions are cases (3) and (4).

    def spam():
        # globals is a builtin.
        print(globals()['__name__'])

    if __name__ == '__main__':
        interp = interpreters.create()
        interp.call(spam)
        # prints: __main__
 In case (3), the function is also copied, but efficiently and only
 temporarily (long enough to be called) and is not actually bound to
 any module.  This temporary function object's :data:`!__name__` will
 be set to match the code object, but the :data:`!__module__`,
 :data:`!__qualname__`, and other attributes are not guaranteed to
 be set.  This shouldn't be a problem in practice, though, since
 introspecting the currently running function is fairly rare.

 There are very few cases where that matters, though.
 We'll cover case (4) in
 :ref:`the next section <interp-tutorial-funcs-in-main>`.

 Otherwise, functions defined in modules other than :mod:`!__main__` run
 inthat module::
 In all the cases, the function will get any global variables from the
 module (inthe target interpreter), like normal::

    from concurrent import interpreters
    from mymod import spam
    def spam():
        print(__name__)

 For a function actually defined in the :mod:`!__main__` module,
 it executes in a separate dummy module, in order to not pollute
 the :mod:`!__main__` module::
 Note, however, that in case (3) functions rarely look up any globals.

 .. _interp-tutorial-funcs-in-main:

 Functions Defined in __main__
 -----------------------------

 Functions defined in :mod:`!__main__` are treated specially by
 :meth:`Interpreter.call`.  This is because the script or module that
 ran in the main interpreter will have not run in other interpreters,
 so any functions defined in the script would only be accessible by
 running it in the target interpreter first.  That is essentially
 how :meth:`Interpreter.call` handles it.

 If the function isn't found in the target interpreter's :mod:`!__main__`
 module then the script that ran in the main interpreter gets run in the
 target interpreter, though under a different name than "__main__".
 The function is then looked up on that resulting fake __main__ module.
 For example::

    from concurrent import interpreters

        interp.call(spam)
        # prints: '<fake __main__>'

 This means global state used in such a function won't be reflected
 The dummy module is never added to :data:`sys.modules`, though it may
 be cached away internally.

 This approach with a fake :mod:`!__main__` module means we can avoid
 polluting the :mod:`!__main__` module of the target interpreter.  It
 also means global state used in such a function won't be reflected
 in the interpreter's :mod:`!__main__` module::

    from textwrap import dedent
        print(total)
        # prints: 0

 Note that the recommended ``if __name__ == '__main__`:`` idiom is
 especially important for such functions, since the script will be
 executed with :data:`!__name__` set to something other than
 :mod:`!__main__`.  Thus, for any code you don't want run repeatedly,
 put it in the if block.  You will probably only want functions or
 classes outside the if block.

 Calling Methods and Other Objects in an Interpreter
 ---------------------------------------------------
        assert res is not data
        assert data == dict(a=1, b=2, c=3)

 .. _interp-tutorial-shareable:

 Supported and Unsupported Objects
 ---------------------------------