U
|
Z ±d] ã @ sR d dl mZmZ d dlmZmZ d dlZG dd dedZG dd dedZG d d
|
d
|
edZ G d d d edZ
|
G d d dedZ G dd de Z G dd de Z G dd de e ZG dd deZedZedddZeddd Zed e dd ZG d d d e ee ZG d!d" d"e ee ZG d#d$ d$e ee ZG d%d& d&ee ee ZdS )'é )ÚABCMetaÚabstractmethod)ÚGenericÚTypeVarNc @ s8 e Zd ZdZdZedd Zedd Zedd Zd S )
|
ÚClockz)The interface for custom run loop clocks.© c C s dS )zZDo any setup this clock might need.
|
|
Called at the beginning of the run.
|
|
Nr ©Úselfr r ú@d:\z\workplace\vscode\pyvenv\venv\Lib\site-packages\trio/_abc.pyÚ start_clock s zClock.start_clockc C s dS )zæReturn the current time, according to this clock.
|
|
This is used to implement functions like :func:`trio.current_time` and
|
:func:`trio.move_on_after`.
|
|
Returns:
|
float: The current time.
|
|
Nr r r r r
|
Ú current_time s zClock.current_timec C s dS )a¥ Compute the real time until the given deadline.
|
|
This is called before we enter a system-specific wait function like
|
:func:`select.select`, to get the timeout to pass.
|
|
For a clock using wall-time, this should be something like::
|
|
return deadline - self.current_time()
|
|
but of course it may be different if you're implementing some kind of
|
virtual clock.
|
|
Args:
|
deadline (float): The absolute time of the next deadline,
|
according to this clock.
|
|
Returns:
|
float: The number of real seconds to sleep until the given
|
deadline. May be :data:`math.inf`.
|
|
Nr )r Údeadliner r r
|
Údeadline_to_sleep_time# s z Clock.deadline_to_sleep_timeN) Ú__name__Ú
|
__module__Ú __qualname__Ú__doc__Ú __slots__r r r r r r r r
|
r
|
s
|
|
r )Ú metaclassc @ s\ e Zd ZdZdZdd Zdd Zdd Zd d
|
Zd d Z d d Z
|
dd Z dd Z dd Z dS )Ú
|
InstrumentzÍThe interface for run loop instrumentation.
|
|
Instruments don't have to inherit from this abstract base class, and all
|
of these methods are optional. This class serves mostly as documentation.
|
|
r c C s dS )z,Called at the beginning of :func:`trio.run`.Nr r r r r
|
Ú
|
before_runF s zInstrument.before_runc C s dS )z,Called just before :func:`trio.run` returns.Nr r r r r
|
Ú after_runI s zInstrument.after_runc C s dS )ztCalled when the given task is created.
|
|
Args:
|
task (trio.lowlevel.Task): The new task.
|
|
Nr ©r Ztaskr r r
|
Ú task_spawnedL s zInstrument.task_spawnedc C s dS )zþCalled when the given task becomes runnable.
|
|
It may still be some time before it actually runs, if there are other
|
runnable tasks ahead of it.
|
|
Args:
|
task (trio.lowlevel.Task): The task that became runnable.
|
|
Nr r r r r
|
Útask_scheduledT s zInstrument.task_scheduledc C s dS )zCalled immediately before we resume running the given task.
|
|
Args:
|
task (trio.lowlevel.Task): The task that is about to run.
|
|
Nr r r r r
|
Úbefore_task_step_ s zInstrument.before_task_stepc C s dS )zCalled when we return to the main run loop after a task has yielded.
|
|
Args:
|
task (trio.lowlevel.Task): The task that just ran.
|
|
Nr r r r r
|
Úafter_task_stepg s zInstrument.after_task_stepc C s dS )ztCalled when the given task exits.
|
|
Args:
|
task (trio.lowlevel.Task): The finished task.
|
|
Nr r r r r
|
Ú task_exitedo s zInstrument.task_exitedc C s dS )zCalled before blocking to wait for I/O readiness.
|
|
Args:
|
timeout (float): The number of seconds we are willing to wait.
|
|
Nr ©r Útimeoutr r r
|
Úbefore_io_waitw s zInstrument.before_io_waitc C s dS )zûCalled after handling pending I/O.
|
|
Args:
|
timeout (float): The number of seconds we were willing to
|
wait. This much time may or may not have elapsed, depending on
|
whether any I/O was ready.
|
|
Nr r r r r
|
Ú after_io_wait s zInstrument.after_io_waitN)r r r r r r r r r r r r r r! r r r r
|
r < s r c @ s. e Zd ZdZdZed ddZedd ZdS )
|
ÚHostnameResolverzÈIf you have a custom hostname resolver, then implementing
|
:class:`HostnameResolver` allows you to register this to be used by Trio.
|
|
See :func:`trio.socket.set_custom_hostname_resolver`.
|
|
r r c às dS )u A custom implementation of :func:`~trio.socket.getaddrinfo`.
|
|
Called by :func:`trio.socket.getaddrinfo`.
|
|
If ``host`` is given as a numeric IP address, then
|
:func:`~trio.socket.getaddrinfo` may handle the request itself rather
|
than calling this method.
|
|
Any required IDNA encoding is handled before calling this function;
|
your implementation can assume that it will never see U-labels like
|
``"café.com"``, and only needs to handle A-labels like
|
``b"xn--caf-dma.com"``.
|
|
Nr )r ÚhostÚportÚfamilyÚtypeÚprotoÚflagsr r r
|
Ú getaddrinfo s z HostnameResolver.getaddrinfoc à s dS )zzA custom implementation of :func:`~trio.socket.getnameinfo`.
|
|
Called by :func:`trio.socket.getnameinfo`.
|
|
Nr )r Zsockaddrr( r r r
|
Ú getnameinfo¥ s z HostnameResolver.getnameinfoN)r r r r )r r r r r r r) r* r r r r
|
r" s r" c @ s e Zd ZdZedddZdS )Ú SocketFactoryzÆIf you write a custom class implementing the Trio socket interface,
|
then you can use a :class:`SocketFactory` to get Trio to use it.
|
|
See :func:`trio.socket.set_custom_socket_factory`.
|
|
Nc C s dS )a& Create and return a socket object.
|
|
Your socket object must inherit from :class:`trio.socket.SocketType`,
|
which is an empty class whose only purpose is to "mark" which classes
|
should be considered valid Trio sockets.
|
|
Called by :func:`trio.socket.socket`.
|
|
Note that unlike :func:`trio.socket.socket`, this does not take a
|
``fileno=`` argument. If a ``fileno=`` is specified, then
|
:func:`trio.socket.socket` returns a regular Trio socket object
|
instead of calling this method.
|
|
Nr )r r% r& r' r r r
|
Úsocket¶ s zSocketFactory.socket)NNN)r r r r r r, r r r r
|
r+ ® s r+ c @ s0 e Zd ZdZdZedd Zdd Zdd Zd S )
|
Ú AsyncResourcea A standard interface for resources that needs to be cleaned up, and
|
where that cleanup may require blocking operations.
|
|
This class distinguishes between "graceful" closes, which may perform I/O
|
and thus block, and a "forceful" close, which cannot. For example, cleanly
|
shutting down a TLS-encrypted connection requires sending a "goodbye"
|
message; but if a peer has become non-responsive, then sending this
|
message might block forever, so we may want to just drop the connection
|
instead. Therefore the :meth:`aclose` method is unusual in that it
|
should always close the connection (or at least make its best attempt)
|
*even if it fails*; failure indicates a failure to achieve grace, not a
|
failure to close the connection.
|
|
Objects that implement this interface can be used as async context
|
managers, i.e., you can write::
|
|
async with create_resource() as some_async_resource:
|
...
|
|
Entering the context manager is synchronous (not a checkpoint); exiting it
|
calls :meth:`aclose`. The default implementations of
|
``__aenter__`` and ``__aexit__`` should be adequate for all subclasses.
|
|
r c à s dS )aÓ Close this resource, possibly blocking.
|
|
IMPORTANT: This method may block in order to perform a "graceful"
|
shutdown. But, if this fails, then it still *must* close any
|
underlying resources before returning. An error from this method
|
indicates a failure to achieve grace, *not* a failure to close the
|
connection.
|
|
For example, suppose we call :meth:`aclose` on a TLS-encrypted
|
connection. This requires sending a "goodbye" message; but if the peer
|
has become non-responsive, then our attempt to send this message might
|
block forever, and eventually time out and be cancelled. In this case
|
the :meth:`aclose` method on :class:`~trio.SSLStream` will
|
immediately close the underlying transport stream using
|
:func:`trio.aclose_forcefully` before raising :exc:`~trio.Cancelled`.
|
|
If the resource is already closed, then this method should silently
|
succeed.
|
|
Once this method completes, any other pending or future operations on
|
this resource should generally raise :exc:`~trio.ClosedResourceError`,
|
unless there's a good reason to do otherwise.
|
|
See also: :func:`trio.aclose_forcefully`.
|
|
Nr r r r r
|
Úacloseä s zAsyncResource.aclosec à s | S ©Nr r r r r
|
Ú
|
__aenter__ s zAsyncResource.__aenter__c Ç s | ¡ I d H d S r/ )r. )r Úargsr r r
|
Ú __aexit__ s zAsyncResource.__aexit__N) r r r r r r r. r0 r2 r r r r
|
r- È s
|
r- c @ s, e Zd ZdZdZedd Zedd ZdS )Ú
|
SendStreama( A standard interface for sending data on a byte stream.
|
|
The underlying stream may be unidirectional, or bidirectional. If it's
|
bidirectional, then you probably want to also implement
|
:class:`ReceiveStream`, which makes your object a :class:`Stream`.
|
|
:class:`SendStream` objects also implement the :class:`AsyncResource`
|
interface, so they can be closed by calling :meth:`~AsyncResource.aclose`
|
or using an ``async with`` block.
|
|
If you want to send Python objects rather than raw bytes, see
|
:class:`SendChannel`.
|
|
r c às dS )ai Sends the given data through the stream, blocking if necessary.
|
|
Args:
|
data (bytes, bytearray, or memoryview): The data to send.
|
|
Raises:
|
trio.BusyResourceError: if another task is already executing a
|
:meth:`send_all`, :meth:`wait_send_all_might_not_block`, or
|
:meth:`HalfCloseableStream.send_eof` on this stream.
|
trio.BrokenResourceError: if something has gone wrong, and the stream
|
is broken.
|
trio.ClosedResourceError: if you previously closed this stream
|
object, or if another task closes this stream object while
|
:meth:`send_all` is running.
|
|
Most low-level operations in Trio provide a guarantee: if they raise
|
:exc:`trio.Cancelled`, this means that they had no effect, so the
|
system remains in a known state. This is **not true** for
|
:meth:`send_all`. If this operation raises :exc:`trio.Cancelled` (or
|
any other exception for that matter), then it may have sent some, all,
|
or none of the requested data, and there is no way to know which.
|
|
Nr ©r Údatar r r
|
Úsend_all s zSendStream.send_allc à s dS )aÆ
|
Block until it's possible that :meth:`send_all` might not block.
|
|
This method may return early: it's possible that after it returns,
|
:meth:`send_all` will still block. (In the worst case, if no better
|
implementation is available, then it might always return immediately
|
without blocking. It's nice to do better than that when possible,
|
though.)
|
|
This method **must not** return *late*: if it's possible for
|
:meth:`send_all` to complete without blocking, then it must
|
return. When implementing it, err on the side of returning early.
|
|
Raises:
|
trio.BusyResourceError: if another task is already executing a
|
:meth:`send_all`, :meth:`wait_send_all_might_not_block`, or
|
:meth:`HalfCloseableStream.send_eof` on this stream.
|
trio.BrokenResourceError: if something has gone wrong, and the stream
|
is broken.
|
trio.ClosedResourceError: if you previously closed this stream
|
object, or if another task closes this stream object while
|
:meth:`wait_send_all_might_not_block` is running.
|
|
Note:
|
|
This method is intended to aid in implementing protocols that want
|
to delay choosing which data to send until the last moment. E.g.,
|
suppose you're working on an implementation of a remote display server
|
like `VNC
|
<https://en.wikipedia.org/wiki/Virtual_Network_Computing>`__, and
|
the network connection is currently backed up so that if you call
|
:meth:`send_all` now then it will sit for 0.5 seconds before actually
|
sending anything. In this case it doesn't make sense to take a
|
screenshot, then wait 0.5 seconds, and then send it, because the
|
screen will keep changing while you wait; it's better to wait 0.5
|
seconds, then take the screenshot, and then send it, because this
|
way the data you deliver will be more
|
up-to-date. Using :meth:`wait_send_all_might_not_block` makes it
|
possible to implement the better strategy.
|
|
If you use this method, you might also want to read up on
|
``TCP_NOTSENT_LOWAT``.
|
|
Further reading:
|
|
* `Prioritization Only Works When There's Pending Data to Prioritize
|
<https://insouciant.org/tech/prioritization-only-works-when-theres-pending-data-to-prioritize/>`__
|
|
* WWDC 2015: Your App and Next Generation Networks: `slides
|
<http://devstreaming.apple.com/videos/wwdc/2015/719ui2k57m/719/719_your_app_and_next_generation_networks.pdf?dl=1>`__,
|
`video and transcript
|
<https://developer.apple.com/videos/play/wwdc2015/719/>`__
|
|
Nr r r r r
|
Ú wait_send_all_might_not_block4 s z(SendStream.wait_send_all_might_not_blockN)r r r r r r r6 r7 r r r r
|
r3 s
|
r3 c @ s2 e Zd ZdZdZed
|
ddZdd Zdd ZdS ) Ú ReceiveStreamaS A standard interface for receiving data on a byte stream.
|
|
The underlying stream may be unidirectional, or bidirectional. If it's
|
bidirectional, then you probably want to also implement
|
:class:`SendStream`, which makes your object a :class:`Stream`.
|
|
:class:`ReceiveStream` objects also implement the :class:`AsyncResource`
|
interface, so they can be closed by calling :meth:`~AsyncResource.aclose`
|
or using an ``async with`` block.
|
|
If you want to receive Python objects rather than raw bytes, see
|
:class:`ReceiveChannel`.
|
|
`ReceiveStream` objects can be used in ``async for`` loops. Each iteration
|
will produce an arbitrary sized chunk of bytes, like calling
|
`receive_some` with no arguments. Every chunk will contain at least one
|
byte, and the loop automatically exits when reaching end-of-file.
|
|
r Nc às dS )a4 Wait until there is data available on this stream, and then return
|
some of it.
|
|
A return value of ``b""`` (an empty bytestring) indicates that the
|
stream has reached end-of-file. Implementations should be careful that
|
they return ``b""`` if, and only if, the stream has reached
|
end-of-file!
|
|
Args:
|
max_bytes (int): The maximum number of bytes to return. Must be
|
greater than zero. Optional; if omitted, then the stream object
|
is free to pick a reasonable default.
|
|
Returns:
|
bytes or bytearray: The data received.
|
|
Raises:
|
trio.BusyResourceError: if two tasks attempt to call
|
:meth:`receive_some` on the same stream at the same time.
|
trio.BrokenResourceError: if something has gone wrong, and the stream
|
is broken.
|
trio.ClosedResourceError: if you previously closed this stream
|
object, or if another task closes this stream object while
|
:meth:`receive_some` is running.
|
|
Nr )r Z max_bytesr r r
|
Ú receive_some s zReceiveStream.receive_somec C s | S r/ r r r r r
|
Ú __aiter__¡ s zReceiveStream.__aiter__c à s | ¡ I d H }|st|S r/ )r9 ÚStopAsyncIterationr4 r r r
|
Ú __anext__¤ s zReceiveStream.__anext__)N) r r r r r r r9 r: r< r r r r
|
r8 m s r8 c @ s e Zd ZdZdZdS )ÚStreamaT A standard interface for interacting with bidirectional byte streams.
|
|
A :class:`Stream` is an object that implements both the
|
:class:`SendStream` and :class:`ReceiveStream` interfaces.
|
|
If implementing this interface, you should consider whether you can go one
|
step further and implement :class:`HalfCloseableStream`.
|
|
r N)r r r r r r r r r
|
r= « s
|
r= c @ s e Zd ZdZdZedd ZdS )ÚHalfCloseableStreamzThis interface extends :class:`Stream` to also allow closing the send
|
part of the stream without closing the receive part.
|
|
r c às dS )u Send an end-of-file indication on this stream, if possible.
|
|
The difference between :meth:`send_eof` and
|
:meth:`~AsyncResource.aclose` is that :meth:`send_eof` is a
|
*unidirectional* end-of-file indication. After you call this method,
|
you shouldn't try sending any more data on this stream, and your
|
remote peer should receive an end-of-file indication (eventually,
|
after receiving all the data you sent before that). But, they may
|
continue to send data to you, and you can continue to receive it by
|
calling :meth:`~ReceiveStream.receive_some`. You can think of it as
|
calling :meth:`~AsyncResource.aclose` on just the
|
:class:`SendStream` "half" of the stream object (and in fact that's
|
literally how :class:`trio.StapledStream` implements it).
|
|
Examples:
|
|
* On a socket, this corresponds to ``shutdown(..., SHUT_WR)`` (`man
|
page <https://linux.die.net/man/2/shutdown>`__).
|
|
* The SSH protocol provides the ability to multiplex bidirectional
|
"channels" on top of a single encrypted connection. A Trio
|
implementation of SSH could expose these channels as
|
:class:`HalfCloseableStream` objects, and calling :meth:`send_eof`
|
would send an ``SSH_MSG_CHANNEL_EOF`` request (see `RFC 4254 §5.3
|
<https://tools.ietf.org/html/rfc4254#section-5.3>`__).
|
|
* On an SSL/TLS-encrypted connection, the protocol doesn't provide any
|
way to do a unidirectional shutdown without closing the connection
|
entirely, so :class:`~trio.SSLStream` implements
|
:class:`Stream`, not :class:`HalfCloseableStream`.
|
|
If an EOF has already been sent, then this method should silently
|
succeed.
|
|
Raises:
|
trio.BusyResourceError: if another task is already executing a
|
:meth:`~SendStream.send_all`,
|
:meth:`~SendStream.wait_send_all_might_not_block`, or
|
:meth:`send_eof` on this stream.
|
trio.BrokenResourceError: if something has gone wrong, and the stream
|
is broken.
|
trio.ClosedResourceError: if you previously closed this stream
|
object, or if another task closes this stream object while
|
:meth:`send_eof` is running.
|
|
Nr r r r r
|
Úsend_eofÁ s z HalfCloseableStream.send_eofN)r r r r r r r? r r r r
|
r> ¹ s r> ÚTÚ ReceiveTypeT)Ú covariantÚSendType)Ú contravariantÚ
|
T_resource)ÚboundrB c @ s e Zd ZdZdZedd ZdS )ÚListenerzÿA standard interface for listening for incoming connections.
|
|
:class:`Listener` objects also implement the :class:`AsyncResource`
|
interface, so they can be closed by calling :meth:`~AsyncResource.aclose`
|
or using an ``async with`` block.
|
|
r c às dS )u Wait until an incoming connection arrives, and then return it.
|
|
Returns:
|
AsyncResource: An object representing the incoming connection. In
|
practice this is generally some kind of :class:`Stream`,
|
but in principle you could also define a :class:`Listener` that
|
returned, say, channel objects.
|
|
Raises:
|
trio.BusyResourceError: if two tasks attempt to call
|
:meth:`accept` on the same listener at the same time.
|
trio.ClosedResourceError: if you previously closed this listener
|
object, or if another task closes this listener object while
|
:meth:`accept` is running.
|
|
Listeners don't generally raise :exc:`~trio.BrokenResourceError`,
|
because for listeners there is no general condition of "the
|
network/remote peer broke the connection" that can be handled in a
|
generic way, like there is for streams. Other errors *can* occur and
|
be raised from :meth:`accept` â for example, if you run out of file
|
descriptors then you might get an :class:`OSError` with its errno set
|
to ``EMFILE``.
|
|
Nr r r r r
|
Úaccept s zListener.acceptN)r r r r r r rH r r r r
|
rG s rG c @ s( e Zd ZdZdZeeddddZdS )Ú SendChannelaH A standard interface for sending Python objects to some receiver.
|
|
`SendChannel` objects also implement the `AsyncResource` interface, so
|
they can be closed by calling `~AsyncResource.aclose` or using an ``async
|
with`` block.
|
|
If you want to send raw bytes rather than Python objects, see
|
`SendStream`.
|
|
r N)ÚvalueÚreturnc à s dS )aD Attempt to send an object through the channel, blocking if necessary.
|
|
Args:
|
value (object): The object to send.
|
|
Raises:
|
trio.BrokenResourceError: if something has gone wrong, and the
|
channel is broken. For example, you may get this if the receiver
|
has already been closed.
|
trio.ClosedResourceError: if you previously closed this
|
:class:`SendChannel` object, or if another task closes it while
|
:meth:`send` is running.
|
trio.BusyResourceError: some channels allow multiple tasks to call
|
`send` at the same time, but others don't. If you try to call
|
`send` simultaneously from multiple tasks on a channel that
|
doesn't support it, then you can get `~trio.BusyResourceError`.
|
|
Nr )r rJ r r r
|
Úsend: s zSendChannel.send)r r r r r r rC rL r r r r
|
rI , s rI c @ s< e Zd ZdZdZeedddZdd Zeddd Z d
|
S ) ÚReceiveChannelap A standard interface for receiving Python objects from some sender.
|
|
You can iterate over a :class:`ReceiveChannel` using an ``async for``
|
loop::
|
|
async for value in receive_channel:
|
...
|
|
This is equivalent to calling :meth:`receive` repeatedly. The loop exits
|
without error when `receive` raises `~trio.EndOfChannel`.
|
|
`ReceiveChannel` objects also implement the `AsyncResource` interface, so
|
they can be closed by calling `~AsyncResource.aclose` or using an ``async
|
with`` block.
|
|
If you want to receive raw bytes rather than Python objects, see
|
`ReceiveStream`.
|
|
r )rK c às dS )a= Attempt to receive an incoming object, blocking if necessary.
|
|
Returns:
|
object: Whatever object was received.
|
|
Raises:
|
trio.EndOfChannel: if the sender has been closed cleanly, and no
|
more objects are coming. This is not an error condition.
|
trio.ClosedResourceError: if you previously closed this
|
:class:`ReceiveChannel` object.
|
trio.BrokenResourceError: if something has gone wrong, and the
|
channel is broken.
|
trio.BusyResourceError: some channels allow multiple tasks to call
|
`receive` at the same time, but others don't. If you try to call
|
`receive` simultaneously from multiple tasks on a channel that
|
doesn't support it, then you can get `~trio.BusyResourceError`.
|
|
Nr r r r r
|
Úreceiveg s zReceiveChannel.receivec C s | S r/ r r r r r
|
r: | s zReceiveChannel.__aiter__c à s0 z| ¡ I d H W S tjk
|
r* tY nX d S r/ )rN ÚtrioZ EndOfChannelr; r r r r
|
r< s zReceiveChannel.__anext__N)
|
r r r r r r rA rN r: r< r r r r
|
rM P s rM c @ s e Zd ZdZdS )ÚChannelzÛA standard interface for interacting with bidirectional channels.
|
|
A `Channel` is an object that implements both the `SendChannel` and
|
`ReceiveChannel` interfaces, so you can both send and receive objects.
|
|
N)r r r r r r r r
|
rP s rP )Úabcr r Útypingr r rO r r r" r+ r- r3 r8 r= r> r@ rA rC rE rG rI rM rP r r r r
|
Ú<module> s& 2N$@e>; '$6
|
