mirror of https://github.com/python/cpython
524 lines
14 KiB
ReStructuredText
524 lines
14 KiB
ReStructuredText
.. currentmodule:: asyncio
|
|
|
|
|
|
===================
|
|
Low-level API Index
|
|
===================
|
|
|
|
This page lists all low-level asyncio APIs.
|
|
|
|
|
|
Obtaining the Event Loop
|
|
========================
|
|
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - :func:`asyncio.get_running_loop`
|
|
- The **preferred** function to get the running event loop.
|
|
|
|
* - :func:`asyncio.get_event_loop`
|
|
- Get an event loop instance (running or current via the current policy).
|
|
|
|
* - :func:`asyncio.set_event_loop`
|
|
- Set the event loop as current via the current policy.
|
|
|
|
* - :func:`asyncio.new_event_loop`
|
|
- Create a new event loop.
|
|
|
|
|
|
.. rubric:: Examples
|
|
|
|
* :ref:`Using asyncio.get_running_loop() <asyncio_example_future>`.
|
|
|
|
|
|
Event Loop Methods
|
|
==================
|
|
|
|
See also the main documentation section about the
|
|
:ref:`asyncio-event-loop-methods`.
|
|
|
|
.. rubric:: Lifecycle
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - :meth:`loop.run_until_complete`
|
|
- Run a Future/Task/awaitable until complete.
|
|
|
|
* - :meth:`loop.run_forever`
|
|
- Run the event loop forever.
|
|
|
|
* - :meth:`loop.stop`
|
|
- Stop the event loop.
|
|
|
|
* - :meth:`loop.close`
|
|
- Close the event loop.
|
|
|
|
* - :meth:`loop.is_running`
|
|
- Return ``True`` if the event loop is running.
|
|
|
|
* - :meth:`loop.is_closed`
|
|
- Return ``True`` if the event loop is closed.
|
|
|
|
* - ``await`` :meth:`loop.shutdown_asyncgens`
|
|
- Close asynchronous generators.
|
|
|
|
|
|
.. rubric:: Debugging
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - :meth:`loop.set_debug`
|
|
- Enable or disable the debug mode.
|
|
|
|
* - :meth:`loop.get_debug`
|
|
- Get the current debug mode.
|
|
|
|
|
|
.. rubric:: Scheduling Callbacks
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - :meth:`loop.call_soon`
|
|
- Invoke a callback soon.
|
|
|
|
* - :meth:`loop.call_soon_threadsafe`
|
|
- A thread-safe variant of :meth:`loop.call_soon`.
|
|
|
|
* - :meth:`loop.call_later`
|
|
- Invoke a callback *after* the given time.
|
|
|
|
* - :meth:`loop.call_at`
|
|
- Invoke a callback *at* the given time.
|
|
|
|
|
|
.. rubric:: Thread/Process Pool
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - ``await`` :meth:`loop.run_in_executor`
|
|
- Run a CPU-bound or other blocking function in
|
|
a :mod:`concurrent.futures` executor.
|
|
|
|
* - :meth:`loop.set_default_executor`
|
|
- Set the default executor for :meth:`loop.run_in_executor`.
|
|
|
|
|
|
.. rubric:: Tasks and Futures
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - :meth:`loop.create_future`
|
|
- Create a :class:`Future` object.
|
|
|
|
* - :meth:`loop.create_task`
|
|
- Schedule coroutine as a :class:`Task`.
|
|
|
|
* - :meth:`loop.set_task_factory`
|
|
- Set a factory used by :meth:`loop.create_task` to
|
|
create :class:`Tasks <Task>`.
|
|
|
|
* - :meth:`loop.get_task_factory`
|
|
- Get the factory :meth:`loop.create_task` uses
|
|
to create :class:`Tasks <Task>`.
|
|
|
|
|
|
.. rubric:: DNS
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - ``await`` :meth:`loop.getaddrinfo`
|
|
- Asynchronous version of :meth:`socket.getaddrinfo`.
|
|
|
|
* - ``await`` :meth:`loop.getnameinfo`
|
|
- Asynchronous version of :meth:`socket.getnameinfo`.
|
|
|
|
|
|
.. rubric:: Networking and IPC
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - ``await`` :meth:`loop.create_connection`
|
|
- Open a TCP connection.
|
|
|
|
* - ``await`` :meth:`loop.create_server`
|
|
- Create a TCP server.
|
|
|
|
* - ``await`` :meth:`loop.create_unix_connection`
|
|
- Open a Unix socket connection.
|
|
|
|
* - ``await`` :meth:`loop.create_unix_server`
|
|
- Create a Unix socket server.
|
|
|
|
* - ``await`` :meth:`loop.connect_accepted_socket`
|
|
- Wrap a :class:`~socket.socket` into a ``(transport, protocol)``
|
|
pair.
|
|
|
|
* - ``await`` :meth:`loop.create_datagram_endpoint`
|
|
- Open a datagram (UDP) connection.
|
|
|
|
* - ``await`` :meth:`loop.sendfile`
|
|
- Send a file over a transport.
|
|
|
|
* - ``await`` :meth:`loop.start_tls`
|
|
- Upgrade an existing connection to TLS.
|
|
|
|
* - ``await`` :meth:`loop.connect_read_pipe`
|
|
- Wrap a read end of a pipe into a ``(transport, protocol)`` pair.
|
|
|
|
* - ``await`` :meth:`loop.connect_write_pipe`
|
|
- Wrap a write end of a pipe into a ``(transport, protocol)`` pair.
|
|
|
|
|
|
.. rubric:: Sockets
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - ``await`` :meth:`loop.sock_recv`
|
|
- Receive data from the :class:`~socket.socket`.
|
|
|
|
* - ``await`` :meth:`loop.sock_recv_into`
|
|
- Receive data from the :class:`~socket.socket` into a buffer.
|
|
|
|
* - ``await`` :meth:`loop.sock_recvfrom`
|
|
- Receive a datagram from the :class:`~socket.socket`.
|
|
|
|
* - ``await`` :meth:`loop.sock_recvfrom_into`
|
|
- Receive a datagram from the :class:`~socket.socket` into a buffer.
|
|
|
|
* - ``await`` :meth:`loop.sock_sendall`
|
|
- Send data to the :class:`~socket.socket`.
|
|
|
|
* - ``await`` :meth:`loop.sock_sendto`
|
|
- Send a datagram via the :class:`~socket.socket` to the given address.
|
|
|
|
* - ``await`` :meth:`loop.sock_connect`
|
|
- Connect the :class:`~socket.socket`.
|
|
|
|
* - ``await`` :meth:`loop.sock_accept`
|
|
- Accept a :class:`~socket.socket` connection.
|
|
|
|
* - ``await`` :meth:`loop.sock_sendfile`
|
|
- Send a file over the :class:`~socket.socket`.
|
|
|
|
* - :meth:`loop.add_reader`
|
|
- Start watching a file descriptor for read availability.
|
|
|
|
* - :meth:`loop.remove_reader`
|
|
- Stop watching a file descriptor for read availability.
|
|
|
|
* - :meth:`loop.add_writer`
|
|
- Start watching a file descriptor for write availability.
|
|
|
|
* - :meth:`loop.remove_writer`
|
|
- Stop watching a file descriptor for write availability.
|
|
|
|
|
|
.. rubric:: Unix Signals
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - :meth:`loop.add_signal_handler`
|
|
- Add a handler for a :mod:`signal`.
|
|
|
|
* - :meth:`loop.remove_signal_handler`
|
|
- Remove a handler for a :mod:`signal`.
|
|
|
|
|
|
.. rubric:: Subprocesses
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - :meth:`loop.subprocess_exec`
|
|
- Spawn a subprocess.
|
|
|
|
* - :meth:`loop.subprocess_shell`
|
|
- Spawn a subprocess from a shell command.
|
|
|
|
|
|
.. rubric:: Error Handling
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - :meth:`loop.call_exception_handler`
|
|
- Call the exception handler.
|
|
|
|
* - :meth:`loop.set_exception_handler`
|
|
- Set a new exception handler.
|
|
|
|
* - :meth:`loop.get_exception_handler`
|
|
- Get the current exception handler.
|
|
|
|
* - :meth:`loop.default_exception_handler`
|
|
- The default exception handler implementation.
|
|
|
|
|
|
.. rubric:: Examples
|
|
|
|
* :ref:`Using asyncio.new_event_loop() and loop.run_forever()
|
|
<asyncio_example_lowlevel_helloworld>`.
|
|
|
|
* :ref:`Using loop.call_later() <asyncio_example_call_later>`.
|
|
|
|
* Using ``loop.create_connection()`` to implement
|
|
:ref:`an echo-client <asyncio_example_tcp_echo_client_protocol>`.
|
|
|
|
* Using ``loop.create_connection()`` to
|
|
:ref:`connect a socket <asyncio_example_create_connection>`.
|
|
|
|
* :ref:`Using add_reader() to watch an FD for read events
|
|
<asyncio_example_watch_fd>`.
|
|
|
|
* :ref:`Using loop.add_signal_handler() <asyncio_example_unix_signals>`.
|
|
|
|
* :ref:`Using loop.subprocess_exec() <asyncio_example_subprocess_proto>`.
|
|
|
|
|
|
Transports
|
|
==========
|
|
|
|
All transports implement the following methods:
|
|
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - :meth:`transport.close() <BaseTransport.close>`
|
|
- Close the transport.
|
|
|
|
* - :meth:`transport.is_closing() <BaseTransport.is_closing>`
|
|
- Return ``True`` if the transport is closing or is closed.
|
|
|
|
* - :meth:`transport.get_extra_info() <BaseTransport.get_extra_info>`
|
|
- Request for information about the transport.
|
|
|
|
* - :meth:`transport.set_protocol() <BaseTransport.set_protocol>`
|
|
- Set a new protocol.
|
|
|
|
* - :meth:`transport.get_protocol() <BaseTransport.get_protocol>`
|
|
- Return the current protocol.
|
|
|
|
|
|
Transports that can receive data (TCP and Unix connections,
|
|
pipes, etc). Returned from methods like
|
|
:meth:`loop.create_connection`, :meth:`loop.create_unix_connection`,
|
|
:meth:`loop.connect_read_pipe`, etc:
|
|
|
|
.. rubric:: Read Transports
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - :meth:`transport.is_reading() <ReadTransport.is_reading>`
|
|
- Return ``True`` if the transport is receiving.
|
|
|
|
* - :meth:`transport.pause_reading() <ReadTransport.pause_reading>`
|
|
- Pause receiving.
|
|
|
|
* - :meth:`transport.resume_reading() <ReadTransport.resume_reading>`
|
|
- Resume receiving.
|
|
|
|
|
|
Transports that can Send data (TCP and Unix connections,
|
|
pipes, etc). Returned from methods like
|
|
:meth:`loop.create_connection`, :meth:`loop.create_unix_connection`,
|
|
:meth:`loop.connect_write_pipe`, etc:
|
|
|
|
.. rubric:: Write Transports
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - :meth:`transport.write() <WriteTransport.write>`
|
|
- Write data to the transport.
|
|
|
|
* - :meth:`transport.writelines() <WriteTransport.writelines>`
|
|
- Write buffers to the transport.
|
|
|
|
* - :meth:`transport.can_write_eof() <WriteTransport.can_write_eof>`
|
|
- Return :const:`True` if the transport supports sending EOF.
|
|
|
|
* - :meth:`transport.write_eof() <WriteTransport.write_eof>`
|
|
- Close and send EOF after flushing buffered data.
|
|
|
|
* - :meth:`transport.abort() <WriteTransport.abort>`
|
|
- Close the transport immediately.
|
|
|
|
* - :meth:`transport.get_write_buffer_size()
|
|
<WriteTransport.get_write_buffer_size>`
|
|
- Return the current size of the output buffer.
|
|
|
|
* - :meth:`transport.get_write_buffer_limits()
|
|
<WriteTransport.get_write_buffer_limits>`
|
|
- Return high and low water marks for write flow control.
|
|
|
|
* - :meth:`transport.set_write_buffer_limits()
|
|
<WriteTransport.set_write_buffer_limits>`
|
|
- Set new high and low water marks for write flow control.
|
|
|
|
|
|
Transports returned by :meth:`loop.create_datagram_endpoint`:
|
|
|
|
.. rubric:: Datagram Transports
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - :meth:`transport.sendto() <DatagramTransport.sendto>`
|
|
- Send data to the remote peer.
|
|
|
|
* - :meth:`transport.abort() <DatagramTransport.abort>`
|
|
- Close the transport immediately.
|
|
|
|
|
|
Low-level transport abstraction over subprocesses.
|
|
Returned by :meth:`loop.subprocess_exec` and
|
|
:meth:`loop.subprocess_shell`:
|
|
|
|
.. rubric:: Subprocess Transports
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - :meth:`transport.get_pid() <SubprocessTransport.get_pid>`
|
|
- Return the subprocess process id.
|
|
|
|
* - :meth:`transport.get_pipe_transport()
|
|
<SubprocessTransport.get_pipe_transport>`
|
|
- Return the transport for the requested communication pipe
|
|
(*stdin*, *stdout*, or *stderr*).
|
|
|
|
* - :meth:`transport.get_returncode() <SubprocessTransport.get_returncode>`
|
|
- Return the subprocess return code.
|
|
|
|
* - :meth:`transport.kill() <SubprocessTransport.kill>`
|
|
- Kill the subprocess.
|
|
|
|
* - :meth:`transport.send_signal() <SubprocessTransport.send_signal>`
|
|
- Send a signal to the subprocess.
|
|
|
|
* - :meth:`transport.terminate() <SubprocessTransport.terminate>`
|
|
- Stop the subprocess.
|
|
|
|
* - :meth:`transport.close() <SubprocessTransport.close>`
|
|
- Kill the subprocess and close all pipes.
|
|
|
|
|
|
Protocols
|
|
=========
|
|
|
|
Protocol classes can implement the following **callback methods**:
|
|
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - ``callback`` :meth:`connection_made() <BaseProtocol.connection_made>`
|
|
- Called when a connection is made.
|
|
|
|
* - ``callback`` :meth:`connection_lost() <BaseProtocol.connection_lost>`
|
|
- Called when the connection is lost or closed.
|
|
|
|
* - ``callback`` :meth:`pause_writing() <BaseProtocol.pause_writing>`
|
|
- Called when the transport's buffer goes over the high water mark.
|
|
|
|
* - ``callback`` :meth:`resume_writing() <BaseProtocol.resume_writing>`
|
|
- Called when the transport's buffer drains below the low water mark.
|
|
|
|
|
|
.. rubric:: Streaming Protocols (TCP, Unix Sockets, Pipes)
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - ``callback`` :meth:`data_received() <Protocol.data_received>`
|
|
- Called when some data is received.
|
|
|
|
* - ``callback`` :meth:`eof_received() <Protocol.eof_received>`
|
|
- Called when an EOF is received.
|
|
|
|
|
|
.. rubric:: Buffered Streaming Protocols
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - ``callback`` :meth:`get_buffer() <BufferedProtocol.get_buffer>`
|
|
- Called to allocate a new receive buffer.
|
|
|
|
* - ``callback`` :meth:`buffer_updated() <BufferedProtocol.buffer_updated>`
|
|
- Called when the buffer was updated with the received data.
|
|
|
|
* - ``callback`` :meth:`eof_received() <BufferedProtocol.eof_received>`
|
|
- Called when an EOF is received.
|
|
|
|
|
|
.. rubric:: Datagram Protocols
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - ``callback`` :meth:`datagram_received()
|
|
<DatagramProtocol.datagram_received>`
|
|
- Called when a datagram is received.
|
|
|
|
* - ``callback`` :meth:`error_received() <DatagramProtocol.error_received>`
|
|
- Called when a previous send or receive operation raises an
|
|
:class:`OSError`.
|
|
|
|
|
|
.. rubric:: Subprocess Protocols
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - ``callback`` :meth:`~SubprocessProtocol.pipe_data_received`
|
|
- Called when the child process writes data into its
|
|
*stdout* or *stderr* pipe.
|
|
|
|
* - ``callback`` :meth:`~SubprocessProtocol.pipe_connection_lost`
|
|
- Called when one of the pipes communicating with
|
|
the child process is closed.
|
|
|
|
* - ``callback`` :meth:`process_exited()
|
|
<SubprocessProtocol.process_exited>`
|
|
- Called when the child process has exited. It can be called before
|
|
:meth:`~SubprocessProtocol.pipe_data_received` and
|
|
:meth:`~SubprocessProtocol.pipe_connection_lost` methods.
|
|
|
|
|
|
Event Loop Policies
|
|
===================
|
|
|
|
Policies is a low-level mechanism to alter the behavior of
|
|
functions like :func:`asyncio.get_event_loop`. See also
|
|
the main :ref:`policies section <asyncio-policies>` for more
|
|
details.
|
|
|
|
|
|
.. rubric:: Accessing Policies
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - :meth:`asyncio.get_event_loop_policy`
|
|
- Return the current process-wide policy.
|
|
|
|
* - :meth:`asyncio.set_event_loop_policy`
|
|
- Set a new process-wide policy.
|
|
|
|
* - :class:`AbstractEventLoopPolicy`
|
|
- Base class for policy objects.
|