gh-76785: Multiple Interpreters in the Stdlib (PEP 554)

Doc/library/interpreters.rst

@@ -0,0 +1,188 @@
+:mod:`interpreters` --- High-level Subinterpreters Module
+==========================================================
+
+.. module:: interpreters
+ :synopsis: High-level SubInterpreters Module.
+
+**Source code:** :source:`Lib/interpreters.py`
+
+--------------
+
+This module provides high-level tools for working with sub-interpreters,
+such as creating them, running code in them, or sending data between them.
+It is a wrapper around the low-level `_interpreters` module.
+
+.. versionchanged:: added in 3.9
+
+Interpreter Objects
+-------------------
+
+The Interpreter object represents a single interpreter.
+.. class:: Interpreter(id)
+
+ The class implementing a subinterpreter object.
+
+ .. method:: is_running()
+
+ Return whether or not the identified interpreter is running.
+ It returns `True` and `False` otherwise.
+
+ .. method:: destroy()
+
+ Destroy the interpreter. Attempting to destroy the current
+ interpreter results in a `RuntimeError`.
+
+ .. method:: run(self, src_str, /, *, channels=None):
+
+ Run the given source code in the interpreter. This blocks
+ the current thread until done. `channels` should be in
+ the form : `(RecvChannel, SendChannel)`.
+
+RecvChannel Objects
+-------------------
+
+The RecvChannel object represents a recieving channel.
+
+.. class:: RecvChannel(id)
+
+ This class represents the receiving end of a channel.
+
+ .. method:: recv()
+
+ Get the next object from the channel, and wait if
+ none have been sent. Associate the interpreter
+ with the channel.
+
+ .. method:: recv_nowait(default=None)
+
+ Like ``recv()``, but return the default result
+ instead of waiting.
+
+ .. method:: release()
+
+ Release the channel for the current interpreter.
+ By default both ends are released. Releasing an already
+ released end results in a ``ChannelReleasedError`` exception.
+
+ .. method:: close(force=False)
+
+ Close the channel in all interpreters. By default
+ both ends are closed. closing an already closed end
+ results in a ``ChannelClosedError`` exception. Without
+ seeting ``force`` to ``True`` a ``ChannelNotEmptyError``
+ will be returned when a channel with data is closed.
+
+
+SendChannel Objects
+--------------------
+
+The ``SendChannel`` object represents a sending channel.
+
+.. class:: SendChannel(id)
+
+ This class represents the sending end of a channel.
+
+ .. method:: send(obj)
+
+ Send the object ``obj`` to the receiving end of the channel
+ and wait. Associate the interpreter with the channel.
+
+ .. method:: send_nowait(obj)
+
+ Like ``send()`` but return ``False`` if not received.
+
+ .. method:: send_buffer(obj)
+
+ Send the object's buffer to the receiving end of the
+ channel and wait. Associate the interpreter with the
+ channel.
+
+ .. method:: send_buffer_nowait(obj)
+
+ Like ``send_buffer()`` but return ``False`` if not received.
+
+ .. method:: release()
+
+ Release the channel for the current interpreter.
+ By default both ends are released. Releasing an already
+ released end results in a ``ChannelReleasedError`` exception.
+
+ .. method:: close(force=False)
+
+ Close the channel in all interpreters. By default
+ both ends are closed. closing an already closed end
+ results in a ``ChannelClosedError`` exception.
+
+
+This module defines the following global functions:
+
+
+.. function:: is_shareable(obj)
+
+ Return ``True`` if the object's data can be shared between
+ interpreters.
+
+.. function:: create_channel()
+
+ Create a new channel for passing data between interpreters.
+
+.. function:: list_all_channels()
+
+ Return all open channels.
+
+.. function:: create()
+
+ Initialize a new (idle) Python interpreter. Get the currently
+ running interpreter. This method returns an ``Interpreter`` object.
+
+.. function:: get_current()
+
+ Get the currently running interpreter. This method returns
+ an ``Interpreter`` object.
+
+.. function:: list_all()
+
+ Get all existing interpreters. Returns a list
+ of ``Interpreter`` objects.
+
+This module also defines the following exceptions.
+
+.. exception:: RunFailedError
+
+ This exception, a subclass of :exc:`RuntimeError`, is raised when the
+ ``Interpreter.run()`` results in an uncaught exception.
+
+.. exception:: ChannelError
+
+ This exception is a subclass of :exc:`Exception`, and is the base
+ class for all channel-related exceptions.
+
+.. exception:: ChannelNotFoundError
+
+ This exception is a subclass of :exc:`ChannelError`, and is raised
+ when the the identified channel is not found.
+
+.. exception:: ChannelEmptyError
+
+ This exception is a subclass of :exc:`ChannelError`, and is raised when
+ the channel is unexpectedly empty.
+
+.. exception:: ChannelNotEmptyError
+
+ This exception is a subclass of :exc:`ChannelError`, and is raised when
+ the channel is unexpectedly not empty.
+
+.. exception:: NotReceivedError
+
+ This exception is a subclass of :exc:`ChannelError`, and is raised when
+ nothing was waiting to receive a sent object.
+
+.. exception:: ChannelClosedError
+
+ This exception is a subclass of :exc:`ChannelError`, and is raised when
+ the channel is closed.
+
+.. exception:: ChannelReleasedError
+
+ This exception is a subclass of :exc:`ChannelClosedError`, and is raised
+ when the channel is released (but not yet closed).