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

    * - :func:`create_task`
      - Start an asyncio Task.

    * - ``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:`current_task`
      - Return the current Task.

    * - :func:`all_tasks`
      - Return all tasks for an event loop.

    * - :class:`Task`
      - Task object.

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


.. rubric:: Examples

* :ref:`Using asyncio.Event <asyncio_example_sync_event>`.

* See also the documentation of asyncio
  :ref:`synchronization primitives <asyncio-sync>`.


Exceptions
==========

.. list-table::
    :widths: 50 50
    :class: full-width-table


    * - :exc:`asyncio.TimeoutError`
      - Raised on timeout by functions like :func:`wait_for`.
        Keep in mind that ``asyncio.TimeoutError`` is **unrelated**
        to the built-in :exc:`TimeoutError` exception.

    * - :exc:`asyncio.CancelledError`
      - Raised when a Task is cancelled. See also :meth:`Task.cancel`.


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