PEP 554: Fix formatting for module API. (#947)
* Fix formatting of module API descriptions. * Fix the API tables.
This commit is contained in:
Eric Snow
GitHub
parent
3a58dceead
commit
6a6f3efde1
618
pep-0554.rst
618
pep-0554.rst
|
|
@ -64,128 +64,127 @@ the `"interpreters" Module API`_ section below.
|
|||
|
||||
For creating and using interpreters:
|
||||
|
||||
+------------------------------+----------------------------------------------+
|
||||
| signature | description |
|
||||
+==============================+==============================================+
|
||||
| list_all() -> [Intepreter] | Get all existing interpreters. |
|
||||
+------------------------------+----------------------------------------------+
|
||||
| get_current() -> Interpreter | Get the currently running interpreter. |
|
||||
+------------------------------+----------------------------------------------+
|
||||
| create() -> Interpreter | Initialize a new (idle) Python interpreter. |
|
||||
+------------------------------+----------------------------------------------+
|
||||
+----------------------------------+----------------------------------------------+
|
||||
| signature | description |
|
||||
+==================================+==============================================+
|
||||
| ``list_all() -> [Intepreter]`` | Get all existing interpreters. |
|
||||
+----------------------------------+----------------------------------------------+
|
||||
| ``get_current() -> Interpreter`` | Get the currently running interpreter. |
|
||||
+----------------------------------+----------------------------------------------+
|
||||
| ``create() -> Interpreter`` | Initialize a new (idle) Python interpreter. |
|
||||
+----------------------------------+----------------------------------------------+
|
||||
|
||||
|
|
||||
|
||||
+-----------------------+-----------------------------------------------------+
|
||||
| signature | description |
|
||||
+=======================+=====================================================+
|
||||
| class Interpreter(id) | A single interpreter. |
|
||||
+-----------------------+-----------------------------------------------------+
|
||||
| .id | The interpreter's ID (read-only). |
|
||||
+-----------------------+-----------------------------------------------------+
|
||||
| .is_running() -> bool | Is the interpreter currently executing code? |
|
||||
+-----------------------+-----------------------------------------------------+
|
||||
| .destroy() | Finalize and destroy the interpreter. |
|
||||
+-----------------------+-----------------------------------------------------+
|
||||
| .run(src_str, /, \*, | | Run the given source code in the interpreter. |
|
||||
| channels=None) | | (This blocks the current thread until done.) |
|
||||
+-----------------------+-----------------------------------------------------+
|
||||
+----------------------------------------+-----------------------------------------------------+
|
||||
| signature | description |
|
||||
+========================================+=====================================================+
|
||||
| ``class Interpreter(id)`` | A single interpreter. |
|
||||
+----------------------------------------+-----------------------------------------------------+
|
||||
| ``.id`` | The interpreter's ID (read-only). |
|
||||
+----------------------------------------+-----------------------------------------------------+
|
||||
| ``.is_running() -> bool`` | Is the interpreter currently executing code? |
|
||||
+----------------------------------------+-----------------------------------------------------+
|
||||
| ``.destroy()`` | Finalize and destroy the interpreter. |
|
||||
+----------------------------------------+-----------------------------------------------------+
|
||||
| ``.run(src_str, /, *, channels=None)`` | | Run the given source code in the interpreter. |
|
||||
| | | (This blocks the current thread until done.) |
|
||||
+----------------------------------------+-----------------------------------------------------+
|
||||
|
||||
|
|
||||
|
||||
+----------------+--------------+------------------------------------------------------+
|
||||
| exception | base | description |
|
||||
+================+==============+======================================================+
|
||||
| RunFailedError | RuntimeError | Interpreter.run() resulted in an uncaught exception. |
|
||||
+----------------+--------------+------------------------------------------------------+
|
||||
+--------------------+------------------+------------------------------------------------------+
|
||||
| exception | base | description |
|
||||
+====================+==================+======================================================+
|
||||
| ``RunFailedError`` | ``RuntimeError`` | Interpreter.run() resulted in an uncaught exception. |
|
||||
+--------------------+------------------+------------------------------------------------------+
|
||||
|
||||
For sharing data between interpreters:
|
||||
|
||||
+--------------------------------+--------------------------------------------+
|
||||
| signature | description |
|
||||
+================================+============================================+
|
||||
| is_shareable(obj) -> Bool | | Can the object's data be shared |
|
||||
| | | between interpreters? |
|
||||
+--------------------------------+--------------------------------------------+
|
||||
| create_channel() -> | | Create a new channel for passing |
|
||||
| (RecvChannel, SendChannel) | | data between interpreters. |
|
||||
+--------------------------------+--------------------------------------------+
|
||||
| list_all_channels() -> | Get all open channels. |
|
||||
| [(RecvChannel, SendChannel)] | |
|
||||
+--------------------------------+--------------------------------------------+
|
||||
+---------------------------------------------------------+--------------------------------------------+
|
||||
| signature | description |
|
||||
+=========================================================+============================================+
|
||||
| ``is_shareable(obj) -> Bool`` | | Can the object's data be shared |
|
||||
| | | between interpreters? |
|
||||
+---------------------------------------------------------+--------------------------------------------+
|
||||
| ``create_channel() -> (RecvChannel, SendChannel)`` | | Create a new channel for passing |
|
||||
| | | data between interpreters. |
|
||||
+---------------------------------------------------------+--------------------------------------------+
|
||||
| ``list_all_channels() -> [(RecvChannel, SendChannel)]`` | Get all open channels. |
|
||||
+---------------------------------------------------------+--------------------------------------------+
|
||||
|
||||
|
|
||||
|
||||
+-------------------------------+-----------------------------------------------+
|
||||
| signature | description |
|
||||
+===============================+===============================================+
|
||||
| class RecvChannel(id) | The receiving end of a channel. |
|
||||
+-------------------------------+-----------------------------------------------+
|
||||
| .id | The channel's unique ID. |
|
||||
+-------------------------------+-----------------------------------------------+
|
||||
| .interpreters | The list of associated interpreters. |
|
||||
+-------------------------------+-----------------------------------------------+
|
||||
| .recv() -> object | | Get the next object from the channel, |
|
||||
| | | and wait if none have been sent. |
|
||||
| | | Associate the interpreter with the channel. |
|
||||
+-------------------------------+-----------------------------------------------+
|
||||
| .recv_nowait(default=None) -> | | Like recv(), but return the default |
|
||||
| object | | instead of waiting. |
|
||||
+-------------------------------+-----------------------------------------------+
|
||||
| .release() | | No longer associate the current interpreter |
|
||||
| | | with the channel (on the receiving end). |
|
||||
+-------------------------------+-----------------------------------------------+
|
||||
| .close(force=False) | | Close the channel in all interpreters. |
|
||||
+-------------------------------+-----------------------------------------------+
|
||||
+------------------------------------------+-----------------------------------------------+
|
||||
| signature | description |
|
||||
+==========================================+===============================================+
|
||||
| ``class RecvChannel(id)`` | The receiving end of a channel. |
|
||||
+------------------------------------------+-----------------------------------------------+
|
||||
| ``.id`` | The channel's unique ID. |
|
||||
+------------------------------------------+-----------------------------------------------+
|
||||
| ``.interpreters`` | The list of associated interpreters. |
|
||||
+------------------------------------------+-----------------------------------------------+
|
||||
| ``.recv() -> object`` | | Get the next object from the channel, |
|
||||
| | | and wait if none have been sent. |
|
||||
| | | Associate the interpreter with the channel. |
|
||||
+------------------------------------------+-----------------------------------------------+
|
||||
| ``.recv_nowait(default=None) -> object`` | | Like recv(), but return the default |
|
||||
| | | instead of waiting. |
|
||||
+------------------------------------------+-----------------------------------------------+
|
||||
| ``.release()`` | | No longer associate the current interpreter |
|
||||
| | | with the channel (on the receiving end). |
|
||||
+------------------------------------------+-----------------------------------------------+
|
||||
| ``.close(force=False)`` | | Close the channel in all interpreters. |
|
||||
+------------------------------------------+-----------------------------------------------+
|
||||
|
||||
|
|
||||
|
||||
+---------------------------+-------------------------------------------------+
|
||||
| signature | description |
|
||||
+===========================+=================================================+
|
||||
| class SendChannel(id) | The sending end of a channel. |
|
||||
+---------------------------+-------------------------------------------------+
|
||||
| .id | The channel's unique ID. |
|
||||
+---------------------------+-------------------------------------------------+
|
||||
| .interpreters | The list of associated interpreters. |
|
||||
+---------------------------+-------------------------------------------------+
|
||||
| .send(obj) | | Send the object (i.e. its data) to the |
|
||||
| | | receiving end of the channel and wait. |
|
||||
| | | Associate the interpreter with the channel. |
|
||||
+---------------------------+-------------------------------------------------+
|
||||
| .send_nowait(obj) | | Like send(), but fail if not received. |
|
||||
+---------------------------+-------------------------------------------------+
|
||||
| .send_buffer(obj) | | Send the object's (PEP 3118) buffer to the |
|
||||
| | | receiving end of the channel and wait. |
|
||||
| | | Associate the interpreter with the channel. |
|
||||
+---------------------------+-------------------------------------------------+
|
||||
| .send_buffer_nowait(obj) | | Like send_buffer(), but fail if not received. |
|
||||
+---------------------------+-------------------------------------------------+
|
||||
| .release() | | No longer associate the current interpreter |
|
||||
| | | with the channel (on the sending end). |
|
||||
+---------------------------+-------------------------------------------------+
|
||||
| .close(force=False) | | Close the channel in all interpreters. |
|
||||
+---------------------------+-------------------------------------------------+
|
||||
+------------------------------+-------------------------------------------------+
|
||||
| signature | description |
|
||||
+==============================+=================================================+
|
||||
| ``class SendChannel(id)`` | The sending end of a channel. |
|
||||
+------------------------------+-------------------------------------------------+
|
||||
| ``.id`` | The channel's unique ID. |
|
||||
+------------------------------+-------------------------------------------------+
|
||||
| ``.interpreters`` | The list of associated interpreters. |
|
||||
+------------------------------+-------------------------------------------------+
|
||||
| ``.send(obj)`` | | Send the object (i.e. its data) to the |
|
||||
| | | receiving end of the channel and wait. |
|
||||
| | | Associate the interpreter with the channel. |
|
||||
+------------------------------+-------------------------------------------------+
|
||||
| ``.send_nowait(obj)`` | | Like send(), but fail if not received. |
|
||||
+------------------------------+-------------------------------------------------+
|
||||
| ``.send_buffer(obj)`` | | Send the object's (PEP 3118) buffer to the |
|
||||
| | | receiving end of the channel and wait. |
|
||||
| | | Associate the interpreter with the channel. |
|
||||
+------------------------------+-------------------------------------------------+
|
||||
| ``.send_buffer_nowait(obj)`` | | Like send_buffer(), but fail if not received. |
|
||||
+------------------------------+-------------------------------------------------+
|
||||
| ``.release()`` | | No longer associate the current interpreter |
|
||||
| | | with the channel (on the sending end). |
|
||||
+------------------------------+-------------------------------------------------+
|
||||
| ``.close(force=False)`` | | Close the channel in all interpreters. |
|
||||
+------------------------------+-------------------------------------------------+
|
||||
|
||||
|
|
||||
|
||||
+----------------------+--------------------+------------------------------------------------+
|
||||
| exception | base | description |
|
||||
+======================+====================+================================================+
|
||||
| ChannelError | Exception | The base class for channel-related exceptions. |
|
||||
+----------------------+--------------------+------------------------------------------------+
|
||||
| ChannelNotFoundError | ChannelError | The identified channel was not found. |
|
||||
+----------------------+--------------------+------------------------------------------------+
|
||||
| ChannelEmptyError | ChannelError | The channel was unexpectedly empty. |
|
||||
+----------------------+--------------------+------------------------------------------------+
|
||||
| ChannelNotEmptyError | ChannelError | The channel was unexpectedly not empty. |
|
||||
+----------------------+--------------------+------------------------------------------------+
|
||||
| NotReceivedError | ChannelError | Nothing was waiting to receive a sent object. |
|
||||
+----------------------+--------------------+------------------------------------------------+
|
||||
| ChannelClosedError | ChannelError | The channel is closed. |
|
||||
+----------------------+--------------------+------------------------------------------------+
|
||||
| ChannelReleasedError | ChannelClosedError | The channel is released (but not yet closed). |
|
||||
+----------------------+--------------------+------------------------------------------------+
|
||||
+--------------------------+------------------------+------------------------------------------------+
|
||||
| exception | base | description |
|
||||
+==========================+========================+================================================+
|
||||
| ``ChannelError`` | ``Exception`` | The base class for channel-related exceptions. |
|
||||
+--------------------------+------------------------+------------------------------------------------+
|
||||
| ``ChannelNotFoundError`` | ``ChannelError`` | The identified channel was not found. |
|
||||
+--------------------------+------------------------+------------------------------------------------+
|
||||
| ``ChannelEmptyError`` | ``ChannelError`` | The channel was unexpectedly empty. |
|
||||
+--------------------------+------------------------+------------------------------------------------+
|
||||
| ``ChannelNotEmptyError`` | ``ChannelError`` | The channel was unexpectedly not empty. |
|
||||
+--------------------------+------------------------+------------------------------------------------+
|
||||
| ``NotReceivedError`` | ``ChannelError`` | Nothing was waiting to receive a sent object. |
|
||||
+--------------------------+------------------------+------------------------------------------------+
|
||||
| ``ChannelClosedError`` | ``ChannelError`` | The channel is closed. |
|
||||
+--------------------------+------------------------+------------------------------------------------+
|
||||
| ``ChannelReleasedError`` | ``ChannelClosedError`` | The channel is released (but not yet closed). |
|
||||
+--------------------------+------------------------+------------------------------------------------+
|
||||
|
||||
|
||||
Examples
|
||||
|
|
@ -656,96 +655,102 @@ TBD
|
|||
* micropython: ???
|
||||
|
||||
|
||||
.. _interpreters-list-all:
|
||||
.. _interpreters-get-current:
|
||||
.. _interpreters-create:
|
||||
.. _interpreters-Interpreter:
|
||||
|
||||
"interpreters" Module API
|
||||
=========================
|
||||
|
||||
The module provides the following functions:
|
||||
The module provides the following functions::
|
||||
|
||||
``list_all()``::
|
||||
list_all() -> [Interpreter]
|
||||
|
||||
Return a list of all existing interpreters.
|
||||
Return a list of all existing interpreters.
|
||||
|
||||
``get_current()``::
|
||||
get_current() => Interpreter
|
||||
|
||||
Return the currently running interpreter.
|
||||
Return the currently running interpreter.
|
||||
|
||||
``create()``::
|
||||
create() -> Interpreter
|
||||
|
||||
Initialize a new Python interpreter and return it. The
|
||||
interpreter will be created in the current thread and will remain
|
||||
idle until something is run in it. The interpreter may be used
|
||||
in any thread and will run in whichever thread calls
|
||||
``interp.run()``.
|
||||
Initialize a new Python interpreter and return it. The
|
||||
interpreter will be created in the current thread and will remain
|
||||
idle until something is run in it. The interpreter may be used
|
||||
in any thread and will run in whichever thread calls
|
||||
``interp.run()``.
|
||||
|
||||
|
||||
The module also provides the following class:
|
||||
The module also provides the following class::
|
||||
|
||||
``Interpreter(id)``::
|
||||
class Interpreter(id):
|
||||
|
||||
id:
|
||||
id -> int:
|
||||
|
||||
The interpreter's ID (read-only).
|
||||
The interpreter's ID (read-only).
|
||||
|
||||
is_running():
|
||||
is_running() -> bool:
|
||||
|
||||
Return whether or not the interpreter is currently executing code.
|
||||
Calling this on the current interpreter will always return True.
|
||||
Return whether or not the interpreter is currently executing
|
||||
code. Calling this on the current interpreter will always
|
||||
return True.
|
||||
|
||||
destroy():
|
||||
destroy():
|
||||
|
||||
Finalize and destroy the interpreter.
|
||||
Finalize and destroy the interpreter.
|
||||
|
||||
This may not be called on an already running interpreter. Doing
|
||||
so results in a RuntimeError.
|
||||
This may not be called on an already running interpreter.
|
||||
Doing so results in a RuntimeError.
|
||||
|
||||
run(source_str, /, *, channels=None):
|
||||
run(source_str, /, *, channels=None):
|
||||
|
||||
Run the provided Python source code in the interpreter. If the
|
||||
"channels" keyword argument is provided (and is a mapping of
|
||||
attribute names to channels) then it is added to the interpreter's
|
||||
execution namespace (the interpreter's "__main__" module). If any
|
||||
of the values are not RecvChannel or SendChannel instances
|
||||
then ValueError gets raised.
|
||||
Run the provided Python source code in the interpreter. If
|
||||
the "channels" keyword argument is provided (and is a mapping
|
||||
of attribute names to channels) then it is added to the
|
||||
interpreter's execution namespace (the interpreter's
|
||||
"__main__" module). If any of the values are not RecvChannel
|
||||
or SendChannel instances then ValueError gets raised.
|
||||
|
||||
This may not be called on an already running interpreter. Doing
|
||||
so results in a RuntimeError.
|
||||
This may not be called on an already running interpreter.
|
||||
Doing so results in a RuntimeError.
|
||||
|
||||
A "run()" call is similar to a function call. Once it completes,
|
||||
the code that called "run()" continues executing (in the original
|
||||
interpreter). Likewise, if there is any uncaught exception then
|
||||
it effectively (see below) propagates into the code where
|
||||
``run()`` was called. However, unlike function calls (but like
|
||||
threads), there is no return value. If any value is needed, pass
|
||||
it out via a channel.
|
||||
A "run()" call is similar to a function call. Once it
|
||||
completes, the code that called "run()" continues executing
|
||||
(in the original interpreter). Likewise, if there is any
|
||||
uncaught exception then it effectively (see below) propagates
|
||||
into the code where ``run()`` was called. However, unlike
|
||||
function calls (but like threads), there is no return value.
|
||||
If any value is needed, pass it out via a channel.
|
||||
|
||||
The big difference from functions is that "run()" executes the
|
||||
code in an entirely different interpreter, with entirely separate
|
||||
state. The state of the current interpreter in the current OS
|
||||
thread is swapped out with the state of the target interpreter
|
||||
(the one that will execute the code). When the target finishes
|
||||
executing, the original interpreter gets swapped back in and its
|
||||
execution resumes.
|
||||
The big difference from functions is that "run()" executes
|
||||
the code in an entirely different interpreter, with entirely
|
||||
separate state. The state of the current interpreter in the
|
||||
current OS thread is swapped out with the state of the target
|
||||
interpreter (the one that will execute the code). When the
|
||||
target finishes executing, the original interpreter gets
|
||||
swapped back in and its execution resumes.
|
||||
|
||||
So calling "run()" will effectively cause the current Python
|
||||
thread to pause. Sometimes you won't want that pause, in which
|
||||
case you should make the "run()" call in another thread. To do
|
||||
so, add a function that calls "run()" and then run that function
|
||||
in a normal "threading.Thread".
|
||||
So calling "run()" will effectively cause the current Python
|
||||
thread to pause. Sometimes you won't want that pause, in
|
||||
which case you should make the "run()" call in another thread.
|
||||
To do so, add a function that calls "run()" and then run that
|
||||
function in a normal "threading.Thread".
|
||||
|
||||
Note that the interpreter's state is never reset, neither before
|
||||
"run()" executes the code nor after. Thus the interpreter
|
||||
state is preserved between calls to "run()". This includes
|
||||
"sys.modules", the "builtins" module, and the internal state
|
||||
of C extension modules.
|
||||
Note that the interpreter's state is never reset, neither
|
||||
before "run()" executes the code nor after. Thus the
|
||||
interpreter state is preserved between calls to "run()".
|
||||
This includes "sys.modules", the "builtins" module, and the
|
||||
internal state of C extension modules.
|
||||
|
||||
Also note that "run()" executes in the namespace of the "__main__"
|
||||
module, just like scripts, the REPL, "-m", and "-c". Just as
|
||||
the interpreter's state is not ever reset, the "__main__" module
|
||||
is never reset. You can imagine concatenating the code from each
|
||||
"run()" call into one long script. This is the same as how the
|
||||
REPL operates.
|
||||
Also note that "run()" executes in the namespace of the
|
||||
"__main__" module, just like scripts, the REPL, "-m", and
|
||||
"-c". Just as the interpreter's state is not ever reset, the
|
||||
"__main__" module is never reset. You can imagine
|
||||
concatenating the code from each "run()" call into one long
|
||||
script. This is the same as how the REPL operates.
|
||||
|
||||
Supported code: source text.
|
||||
Supported code: source text.
|
||||
|
||||
|
||||
Uncaught Exceptions
|
||||
|
|
@ -762,6 +767,11 @@ Raising (a proxy of) the exception directly is problematic since it's
|
|||
harder to distinguish between an error in the ``run()`` call and an
|
||||
uncaught exception from the subinterpreter.
|
||||
|
||||
.. _interpreters-is-shareable:
|
||||
.. _interpreters-create-channel:
|
||||
.. _interpreters-list-all-channels:
|
||||
.. _interpreters-RecvChannel:
|
||||
.. _interpreters-SendChannel:
|
||||
|
||||
API for sharing data
|
||||
--------------------
|
||||
|
|
@ -773,16 +783,16 @@ for that here. Instead, only mimimum set of types will be supported.
|
|||
Initially this will include ``None``, ``bytes``, ``str``, ``int``,
|
||||
and channels. Further types may be supported later.
|
||||
|
||||
The ``interpreters`` module provides a way for users to determine
|
||||
whether an object is shareable or not:
|
||||
The ``interpreters`` module provides a function that users may call
|
||||
to determine whether an object is shareable or not::
|
||||
|
||||
``is_shareable(obj)``::
|
||||
is_shareable(obj) -> bool:
|
||||
|
||||
Return True if the object may be shared between interpreters. This
|
||||
does not necessarily mean that the actual objects will be shared.
|
||||
Insead, it means that the objects' underlying data will be shared in
|
||||
a cross-interpreter way, whether via a proxy, a copy, or some other
|
||||
means.
|
||||
Return True if the object may be shared between interpreters.
|
||||
This does not necessarily mean that the actual objects will be
|
||||
shared. Insead, it means that the objects' underlying data will
|
||||
be shared in a cross-interpreter way, whether via a proxy, a
|
||||
copy, or some other means.
|
||||
|
||||
This proposal provides two ways to share such objects between
|
||||
interpreters.
|
||||
|
|
@ -800,155 +810,169 @@ to a pipe. The main difference is that channels can be associated with
|
|||
zero or more interpreters on either end. Unlike queues, which are also
|
||||
many-to-many, channels have no buffer.
|
||||
|
||||
The ``interpreters`` module provides the following functions and
|
||||
classes related to channels:
|
||||
The ``interpreters`` module provides the following functions related
|
||||
to channels::
|
||||
|
||||
``create_channel()``::
|
||||
create_channel() -> (RecvChannel, SendChannel):
|
||||
|
||||
Create a new channel and return (recv, send), the RecvChannel and
|
||||
SendChannel corresponding to the ends of the channel. The channel
|
||||
is not closed and destroyed (i.e. garbage-collected) until the number
|
||||
of associated interpreters returns to 0 (including when the channel
|
||||
is explicitly closed).
|
||||
Create a new channel and return (recv, send), the RecvChannel
|
||||
and SendChannel corresponding to the ends of the channel. The
|
||||
channel is not closed and destroyed (i.e. garbage-collected)
|
||||
until the number of associated interpreters returns to 0
|
||||
(including when the channel is explicitly closed).
|
||||
|
||||
An interpreter gets associated with a channel by calling its "send()"
|
||||
or "recv()" method. That association gets dropped by calling
|
||||
"release()" on the channel.
|
||||
An interpreter gets associated with a channel by calling its
|
||||
"send()" or "recv()" method. That association gets dropped
|
||||
by calling "release()" on the channel.
|
||||
|
||||
Both ends of the channel are supported "shared" objects (i.e. may be
|
||||
safely shared by different interpreters. Thus they may be passed as
|
||||
keyword arguments to "Interpreter.run()".
|
||||
Both ends of the channel are supported "shared" objects (i.e.
|
||||
may be safely shared by different interpreters. Thus they
|
||||
may be passed as keyword arguments to "Interpreter.run()".
|
||||
|
||||
``list_all_channels()``::
|
||||
list_all_channels() -> [(RecvChannel, SendChannel)]:
|
||||
|
||||
Return a list of all open (RecvChannel, SendChannel) pairs.
|
||||
Return a list of all open channel-end pairs.
|
||||
|
||||
The module also provides the following channel-related classes::
|
||||
|
||||
class RecvChannel(id):
|
||||
|
||||
The receiving end of a channel. An interpreter may use this to
|
||||
receive objects from another interpreter. At first only a few
|
||||
of the simple, immutable builtin types will be supported.
|
||||
|
||||
id -> int:
|
||||
|
||||
The channel's unique ID. This is shared with the "send" end.
|
||||
|
||||
interpreters => [Interpreter]:
|
||||
|
||||
The list of interpreters associated with the "recv" end of
|
||||
the channel. That means those that have called the "recv()"
|
||||
(or "recv_nowait()") method, still hold a reference to the
|
||||
channel end, and haven't called "release()". If the
|
||||
channel has been closed then raise
|
||||
ChannelClosedError.
|
||||
|
||||
recv():
|
||||
|
||||
Return the next object (i.e. the data from the sent object)
|
||||
from the channel. If none have been sent then wait until
|
||||
the next send. This associates the current interpreter
|
||||
with the "recv" end of the channel.
|
||||
|
||||
If the channel is already closed then raise ChannelClosedError.
|
||||
If the channel isn't closed but the current interpreter already
|
||||
called the "release()" method for the "recv" end then raise
|
||||
ChannelReleasedError (which is a subclass of
|
||||
ChannelClosedError).
|
||||
|
||||
recv_nowait(default=None):
|
||||
|
||||
Return the next object from the channel. If none have been
|
||||
sent then return the default. Otherwise, this is the same
|
||||
as the "recv()" method.
|
||||
|
||||
release() -> bool:
|
||||
|
||||
No longer associate the current interpreter with the channel
|
||||
(on the "recv" end) and block any future association (via the
|
||||
"recv()" or ``recv_nowait()`` methods). If the interpreter
|
||||
was never associated with the channel then still block any
|
||||
future association. The "send" end of the channel is
|
||||
unaffected by a released "recv" end.
|
||||
|
||||
Once an interpreter is no longer associated with the "recv"
|
||||
end of the channel, any "recv()" and "recv_nowait()" calls
|
||||
from that interpreter will fail (even ongoing calls). See
|
||||
"recv()" for details.
|
||||
|
||||
Once the number of associated interpreters on both ends drops
|
||||
to 0, the channel is actually marked as closed. The Python
|
||||
runtime will garbage collect all closed channels, though it
|
||||
may not happen immediately.
|
||||
|
||||
Note that the interpreter automatically loses its association
|
||||
with the channel end when it is no longer used (i.e. has no
|
||||
references) in that interpreter, as though "release()"
|
||||
were called.
|
||||
|
||||
This operation is idempotent. Return True if "release()"
|
||||
has not been called before by the current interpreter.
|
||||
|
||||
close(force=False):
|
||||
|
||||
Close both ends of the channel (in all interpreters). This
|
||||
means that any further use of the channel anywhere raises
|
||||
ChannelClosedError. If the channel is not empty then
|
||||
raise ChannelNotEmptyError (if "force" is False) or
|
||||
discard the remaining objects (if "force" is True)
|
||||
and close it. Note that the behavior of closing
|
||||
the "send" end is slightly different.
|
||||
|
||||
|
||||
``RecvChannel(id)``::
|
||||
class SendChannel(id):
|
||||
|
||||
The receiving end of a channel. An interpreter may use this to
|
||||
receive objects from another interpreter. At first only a few of
|
||||
the simple, immutable builtin types will be supported.
|
||||
The sending end of a channel. An interpreter may use this to
|
||||
send objects to another interpreter. At first only a few of
|
||||
the simple, immutable builtin types will be supported.
|
||||
|
||||
id:
|
||||
id -> int:
|
||||
|
||||
The channel's unique ID. This is shared with the "send" end.
|
||||
The channel's unique ID. This is shared with the "recv" end.
|
||||
|
||||
interpreters:
|
||||
interpreters -> [Interpreter]:
|
||||
|
||||
The list of associated interpreters: those that have called
|
||||
the "recv()" method and haven't called "release()" (and the
|
||||
channel hasn't been explicitly closed).
|
||||
Like "RecvChannel.interpreters" but for the "send" end.
|
||||
|
||||
recv():
|
||||
send(obj):
|
||||
|
||||
Return the next object (i.e. the data from the sent object) from
|
||||
the channel. If none have been sent then wait until the next
|
||||
send. This associates the current interpreter with the "recv"
|
||||
end of the channel.
|
||||
Send the object (i.e. its data) to the "recv" end of the
|
||||
channel. Wait until the object is received. If the object
|
||||
is not shareable then ValueError is raised. This associates
|
||||
the current interpreter with the "send" end of the channel.
|
||||
|
||||
If the channel is already closed then raise ChannelClosedError.
|
||||
If the channel isn't closed but the current interpreter already
|
||||
called the "release()" method (which drops its association with
|
||||
the channel) then raise ChannelReleasedError (which is a subclass
|
||||
of ChannelClosedError).
|
||||
This associates the current interpreter with the "send" end
|
||||
of the channel. If the channel send was already released
|
||||
by the interpreter then raise ChannelReleasedError. If
|
||||
the channel is already closed then raise
|
||||
ChannelClosedError.
|
||||
|
||||
recv_nowait(default=None):
|
||||
send_nowait(obj):
|
||||
|
||||
Return the next object from the channel. If none have been sent
|
||||
then return the default. Otherwise, this is the same as the
|
||||
"recv()" method.
|
||||
Send the object to the "recv" end of the channel. If no
|
||||
interpreter is currently receiving (waiting on the other
|
||||
end) then raise NotReceivedError. Otherwise this is the
|
||||
same as "send()".
|
||||
|
||||
release():
|
||||
send_buffer(obj):
|
||||
|
||||
No longer associate the current interpreter with the channel (on
|
||||
the receiving end) and block future association (via the "recv()"
|
||||
method). If the interpreter was never associated with the channel
|
||||
then still block future association. Once an interpreter is no
|
||||
longer associated with the channel, subsequent (or current) send()
|
||||
and recv() calls from that interpreter will raise
|
||||
ChannelReleasedError (or ChannelClosedError if the channel
|
||||
is actually marked as closed).
|
||||
Send a MemoryView of the object rather than the object.
|
||||
Otherwise this is the same as "send()". Note that the
|
||||
object must implement the PEP 3118 buffer protocol.
|
||||
|
||||
Once the number of associated interpreters on both ends drops
|
||||
to 0, the channel is actually marked as closed. The Python
|
||||
runtime will garbage collect all closed channels, though it may
|
||||
not be immediately. Note that "release()" is automatically called
|
||||
on behalf of the current interpreter when the channel is no longer
|
||||
used (i.e. has no references) in that interpreter.
|
||||
send_buffer_nowait(obj):
|
||||
|
||||
This operation is idempotent. Return True if "release()" has not
|
||||
been called before by the current interpreter.
|
||||
Send a MemoryView of the object rather than the object.
|
||||
If the other end is not currently receiving then raise
|
||||
NotReceivedError. Otherwise this is the same as
|
||||
"send_buffer()".
|
||||
|
||||
close(force=False):
|
||||
release():
|
||||
|
||||
Close both ends of the channel (in all interpreters). This means
|
||||
that any further use of the channel anywhere raises
|
||||
ChannelClosedError. If the channel is not empty then raise
|
||||
ChannelNotEmptyError (if "force" is False) or discard the
|
||||
remaining objects (if "force" is True) and close it.
|
||||
This is the same as "RecvChannel.release(), but applied
|
||||
to the sending end of the channel.
|
||||
|
||||
close(force=False):
|
||||
|
||||
``SendChannel(id)``::
|
||||
|
||||
The sending end of a channel. An interpreter may use this to send
|
||||
objects to another interpreter. At first only a few of
|
||||
the simple, immutable builtin types will be supported.
|
||||
|
||||
id:
|
||||
|
||||
The channel's unique ID. This is shared with the "recv" end.
|
||||
|
||||
interpreters:
|
||||
|
||||
The list of associated interpreters (those that have called
|
||||
the "send()" method).
|
||||
|
||||
send(obj):
|
||||
|
||||
Send the object (i.e. its data) to the receiving end of the
|
||||
channel. Wait until the object is received. If the the
|
||||
object is not shareable then ValueError is raised. This
|
||||
associates the current interpreter with the "send" end of the
|
||||
channel.
|
||||
|
||||
If the channel is already closed then raise ChannelClosedError.
|
||||
If the channel isn't closed but the current interpreter already
|
||||
called the "release()" method (which drops its association with
|
||||
the channel) then raise ChannelReleasedError.
|
||||
|
||||
send_nowait(obj):
|
||||
|
||||
Send the object to the receiving end of the channel. If no
|
||||
interpreter is currently receiving (waiting on the other end)
|
||||
then raise NotReceivedError. Otherwise this is the same as
|
||||
"send()".
|
||||
|
||||
send_buffer(obj):
|
||||
|
||||
Send a MemoryView of the object rather than the object. Otherwise
|
||||
this is the same as send(). Note that the object must implement
|
||||
the PEP 3118 buffer protocol.
|
||||
|
||||
send_buffer_nowait(obj):
|
||||
|
||||
Send a MemoryView of the object rather than the object. If the
|
||||
other end is not currently receiving then raise NotReceivedError.
|
||||
Otherwise this is the same as "send_buffer()".
|
||||
|
||||
release():
|
||||
|
||||
This is the same as "RecvChannel.release(), but applied to the
|
||||
sending end of the channel.
|
||||
|
||||
close(force=False):
|
||||
|
||||
Close both ends of the channel (in all interpreters). No matter
|
||||
what the "send" end of the channel is immediately closed. If the
|
||||
channel is empty then close the "recv" end immediately too.
|
||||
Otherwise, if "force" if False, close the "recv" end (and hence
|
||||
the full channel) once the channel becomes empty; or, if "force"
|
||||
is True, discard the remaining items and close immediately.
|
||||
Close both ends of the channel (in all interpreters). No
|
||||
matter what the "send" end of the channel is immediately
|
||||
closed. If the channel is empty then close the "recv"
|
||||
end immediately too. Otherwise, if "force" if False,
|
||||
close the "recv" end (and hence the full channel)
|
||||
once the channel becomes empty; or, if "force"
|
||||
is True, discard the remaining items and
|
||||
close immediately.
|
||||
|
||||
Note that ``send_buffer()`` is similar to how
|
||||
``multiprocessing.Connection`` works. [mp-conn]_
|
||||
|
|
|
|||
Loading…
Reference in New Issue