.. 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>.