mirror of
https://github.com/python/cpython.git
synced 2025-11-03 07:01:21 +00:00
2a9e4e4d73
Also rearrange some items in the list. Co-authored-by: Thomas Grainger <tagrain@gmail.com>
235 lines
5 KiB
ReStructuredText
235 lines
5 KiB
ReStructuredText
.. currentmodule:: asyncio
|
|
|
|
|
|
====================
|
|
High-level API Index
|
|
====================
|
|
|
|
This page lists all high-level async/await enabled asyncio APIs.
|
|
|
|
|
|
Tasks
|
|
=====
|
|
|
|
Utilities to run asyncio programs, create Tasks, and
|
|
await on multiple things with timeouts.
|
|
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - :func:`run`
|
|
- Create event loop, run a coroutine, close the loop.
|
|
|
|
* - :class:`Runner`
|
|
- A context manager that simplifies multiple async function calls.
|
|
|
|
* - :class:`Task`
|
|
- Task object.
|
|
|
|
* - :class:`TaskGroup`
|
|
- A context manager that holds a group of tasks. Provides
|
|
a convenient and reliable way to wait for all tasks in the group to
|
|
finish.
|
|
|
|
* - :func:`create_task`
|
|
- Start an asyncio Task, then returns it.
|
|
|
|
* - :func:`current_task`
|
|
- Return the current Task.
|
|
|
|
* - :func:`all_tasks`
|
|
- Return all tasks that are not yet finished for an event loop.
|
|
|
|
* - ``await`` :func:`sleep`
|
|
- Sleep for a number of seconds.
|
|
|
|
* - ``await`` :func:`gather`
|
|
- Schedule and wait for things concurrently.
|
|
|
|
* - ``await`` :func:`wait_for`
|
|
- Run with a timeout.
|
|
|
|
* - ``await`` :func:`shield`
|
|
- Shield from cancellation.
|
|
|
|
* - ``await`` :func:`wait`
|
|
- Monitor for completion.
|
|
|
|
* - :func:`timeout`
|
|
- Run with a timeout. Useful in cases when `wait_for` is not suitable.
|
|
|
|
* - :func:`to_thread`
|
|
- Asynchronously run a function in a separate OS thread.
|
|
|
|
* - :func:`run_coroutine_threadsafe`
|
|
- Schedule a coroutine from another OS thread.
|
|
|
|
* - ``for in`` :func:`as_completed`
|
|
- Monitor for completion with a ``for`` loop.
|
|
|
|
|
|
.. rubric:: Examples
|
|
|
|
* :ref:`Using asyncio.gather() to run things in parallel
|
|
<asyncio_example_gather>`.
|
|
|
|
* :ref:`Using asyncio.wait_for() to enforce a timeout
|
|
<asyncio_example_waitfor>`.
|
|
|
|
* :ref:`Cancellation <asyncio_example_task_cancel>`.
|
|
|
|
* :ref:`Using asyncio.sleep() <asyncio_example_sleep>`.
|
|
|
|
* See also the main :ref:`Tasks documentation page <coroutine>`.
|
|
|
|
|
|
Queues
|
|
======
|
|
|
|
Queues should be used to distribute work amongst multiple asyncio Tasks,
|
|
implement connection pools, and pub/sub patterns.
|
|
|
|
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - :class:`Queue`
|
|
- A FIFO queue.
|
|
|
|
* - :class:`PriorityQueue`
|
|
- A priority queue.
|
|
|
|
* - :class:`LifoQueue`
|
|
- A LIFO queue.
|
|
|
|
|
|
.. rubric:: Examples
|
|
|
|
* :ref:`Using asyncio.Queue to distribute workload between several
|
|
Tasks <asyncio_example_queue_dist>`.
|
|
|
|
* See also the :ref:`Queues documentation page <asyncio-queues>`.
|
|
|
|
|
|
Subprocesses
|
|
============
|
|
|
|
Utilities to spawn subprocesses and run shell commands.
|
|
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - ``await`` :func:`create_subprocess_exec`
|
|
- Create a subprocess.
|
|
|
|
* - ``await`` :func:`create_subprocess_shell`
|
|
- Run a shell command.
|
|
|
|
|
|
.. rubric:: Examples
|
|
|
|
* :ref:`Executing a shell command <asyncio_example_subprocess_shell>`.
|
|
|
|
* See also the :ref:`subprocess APIs <asyncio-subprocess>`
|
|
documentation.
|
|
|
|
|
|
Streams
|
|
=======
|
|
|
|
High-level APIs to work with network IO.
|
|
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - ``await`` :func:`open_connection`
|
|
- Establish a TCP connection.
|
|
|
|
* - ``await`` :func:`open_unix_connection`
|
|
- Establish a Unix socket connection.
|
|
|
|
* - ``await`` :func:`start_server`
|
|
- Start a TCP server.
|
|
|
|
* - ``await`` :func:`start_unix_server`
|
|
- Start a Unix socket server.
|
|
|
|
* - :class:`StreamReader`
|
|
- High-level async/await object to receive network data.
|
|
|
|
* - :class:`StreamWriter`
|
|
- High-level async/await object to send network data.
|
|
|
|
|
|
.. rubric:: Examples
|
|
|
|
* :ref:`Example TCP client <asyncio_example_stream>`.
|
|
|
|
* See also the :ref:`streams APIs <asyncio-streams>`
|
|
documentation.
|
|
|
|
|
|
Synchronization
|
|
===============
|
|
|
|
Threading-like synchronization primitives that can be used in Tasks.
|
|
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
* - :class:`Lock`
|
|
- A mutex lock.
|
|
|
|
* - :class:`Event`
|
|
- An event object.
|
|
|
|
* - :class:`Condition`
|
|
- A condition object.
|
|
|
|
* - :class:`Semaphore`
|
|
- A semaphore.
|
|
|
|
* - :class:`BoundedSemaphore`
|
|
- A bounded semaphore.
|
|
|
|
* - :class:`Barrier`
|
|
- A barrier object.
|
|
|
|
|
|
.. rubric:: Examples
|
|
|
|
* :ref:`Using asyncio.Event <asyncio_example_sync_event>`.
|
|
|
|
* :ref:`Using asyncio.Barrier <asyncio_example_barrier>`.
|
|
|
|
* See also the documentation of asyncio
|
|
:ref:`synchronization primitives <asyncio-sync>`.
|
|
|
|
|
|
Exceptions
|
|
==========
|
|
|
|
.. list-table::
|
|
:widths: 50 50
|
|
:class: full-width-table
|
|
|
|
|
|
* - :exc:`asyncio.CancelledError`
|
|
- Raised when a Task is cancelled. See also :meth:`Task.cancel`.
|
|
|
|
* - :exc:`asyncio.BrokenBarrierError`
|
|
- Raised when a Barrier is broken. See also :meth:`Barrier.wait`.
|
|
|
|
|
|
.. rubric:: Examples
|
|
|
|
* :ref:`Handling CancelledError to run code on cancellation request
|
|
<asyncio_example_task_cancel>`.
|
|
|
|
* See also the full list of
|
|
:ref:`asyncio-specific exceptions <asyncio-exceptions>`.
|