@@ -0,0 +1,218 @@ .. 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:`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>`.