mirror of
https://github.com/python/cpython.git
synced 2025-10-17 20:28:43 +00:00
145 lines
3.8 KiB
ReStructuredText
145 lines
3.8 KiB
ReStructuredText
High-level implementation of Subinterpreters
|
|
============================================
|
|
|
|
**Source code:** :source:`Lib/test/support/_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 ``__xxsubinterpreters`` 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 ``True`` if the identified interpreter is running.
|
|
|
|
.. method:: close()
|
|
|
|
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.
|
|
|
|
|
|
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)
|
|
|
|
Similar to ``send()``, but returns ``False`` if
|
|
*obj* is not immediately received instead of blocking.
|
|
|
|
|
|
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(*, isolated=True)
|
|
|
|
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:: get_main()
|
|
|
|
Get the main 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 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.
|