Improve concurrent.interpreters documentation

Documentation

We need a better documentation for https://docs.python.org/3/library/concurrent.interpreters.html

I tried this, but I don't understand

• how to use queue
• prepare_main purpose
• exec parameters like dedent
• I got funny crashes

####################################################################################################

from concurrent import interpreters as CI
from pprint import pprint
from textwrap import dedent
import queue

####################################################################################################

main_interpreter = CI.get_main()
print(f"Main is {main_interpreter}")

current_interpreter = CI.get_current()
print(f"Current is {current_interpreter}")

queue = CI.create_queue()

def task_runner(index):
    print("Task runner", index)
    print(f"  Current is {current_interpreter}")

    globals_ = globals()
    # pprint(globals_)
    print("  Globals:")
    for key, value in globals().items():
        if key == '__builtins__':
            print(f"    __builtins__: ...")
        else:
            print(f"    {key}: {value}")

    # Crash
    #   Main is Interpreter(0)
    #   Current is Interpreter(1)
    #   concurrent.interpreters.ExecutionFailed: NameError: name 'foo' is not defined
    #! print(foo)

    # Block
    #! print(f"  #{index} from queue {queue.get()}")

    return 'ok'

# if True:
if current_interpreter is main_interpreter:
    # queue = CI.create_queue()

    interpreters = []
    NUMBER_OF_INTERPRETERS = 4
    for i in range(NUMBER_OF_INTERPRETERS):
        _ = CI.create()
        # Bind objects in the interpreter’s __main__ module
        _.prepare_main(ns=None, foo=123)
        interpreters.append(_)

    for _ in CI.list_all():
        print(f"Interpreter id {_.id} running {_.is_running()} whence '{_.whence}'")

    print("Call...")

    print()
    # exec(code, /, dedent=True)
    interpreters[0].exec(dedent('''
    print(f"Exec hello {foo}")
    '''))

    print()
    rc = interpreters[0].call(task_runner, 0)
    print(rc)

    print()
    threads = []
    for i in range(NUMBER_OF_INTERPRETERS):
        thread = interpreters[i].call_in_thread(task_runner, i)
        print(f"Thread #{i} {thread}")
        threads.append(thread)

    NUMBER_OF_TASKS = 10
    for i in range(NUMBER_OF_TASKS):
        queue.put(i)

    for thread in threads:
        thread.join()

    # print()
    # print(queue)

    # Block main
    #! print(queue.get())
    # try:
    # except queue.ShutDown:
    #     pass
else:
    pass

Linked PRs

• gh-145657

Start with the concurrent.interpreters documentation at docs.python.org/3/library/concurrent.interpreters.html and reproduce the provided example. Clarify queue usage, prepare_main, exec parameters such as dedent, and the reported crashes; done means the documentation explains these cases with a working, understandable example.