Index de l'API de haut niveau
*****************************

Cette page répertorie toutes les API *async/await* de haut niveau
disponibles dans l'API *asyncio*.


Tâches
======

Utilitaires pour exécuter des programmes asynchrones, créer des tâches
et attendre plusieurs choses avec des délais maximaux d'attente.

+----------------------------------------------------+----------------------------------------------------+
| "run()"                                            | Crée une boucle d'événements, exécute une          |
|                                                    | coroutine, ferme la boucle.                        |
+----------------------------------------------------+----------------------------------------------------+
| "Runner"                                           | Gestionnaire de contexte qui simplifie plusieurs   |
|                                                    | appels de fonction asynchrones.                    |
+----------------------------------------------------+----------------------------------------------------+
| "Task"                                             | Objet de tâche.                                    |
+----------------------------------------------------+----------------------------------------------------+
| "TaskGroup"                                        | Gestionnaire de contexte pour un groupe de tâches. |
|                                                    | Fournit un moyen pratique et fiable d'attendre la  |
|                                                    | fin de toutes les tâches du groupe.                |
+----------------------------------------------------+----------------------------------------------------+
| "create_task()"                                    | Démarre une tâche asynchrone, puis la renvoie.     |
+----------------------------------------------------+----------------------------------------------------+
| "current_task()"                                   | Renvoie la tâche actuelle.                         |
+----------------------------------------------------+----------------------------------------------------+
| "all_tasks()"                                      | Renvoie toutes les tâches qui ne sont pas encore   |
|                                                    | terminées pour une boucle d'événements.            |
+----------------------------------------------------+----------------------------------------------------+
| "await" "sleep()"                                  | Dort quelques secondes.                            |
+----------------------------------------------------+----------------------------------------------------+
| "await" "gather()"                                 | Planifie et attend des choses concurrentes.        |
+----------------------------------------------------+----------------------------------------------------+
| "await" "wait_for()"                               | Exécute avec un délai d'attente.                   |
+----------------------------------------------------+----------------------------------------------------+
| "await" "shield()"                                 | Empêche l'annulation.                              |
+----------------------------------------------------+----------------------------------------------------+
| "await" "wait()"                                   | Surveille l'achèvement.                            |
+----------------------------------------------------+----------------------------------------------------+
| "timeout()"                                        | Exécute avec un délai d'attente. Utile dans les    |
|                                                    | cas où "wait_for" ne convient pas.                 |
+----------------------------------------------------+----------------------------------------------------+
| "to_thread()"                                      | Exécute de manière asynchrone une fonction dans un |
|                                                    | fil d'exécution séparé.                            |
+----------------------------------------------------+----------------------------------------------------+
| "run_coroutine_threadsafe()"                       | Planifie une coroutine à partir d'un autre fil     |
|                                                    | d'exécution.                                       |
+----------------------------------------------------+----------------------------------------------------+
| "for in" "as_completed()"                          | Surveille l'achèvement avec une boucle "for".      |
+----------------------------------------------------+----------------------------------------------------+

-[ Exemples ]-

* Utilisation d'asyncio.gather() pour exécuter des choses en
  parallèle.

* Utilisation d'asyncio.wait_for() pour appliquer un délai d'attente.

* Annulation.

* Utilisation d'asyncio.sleep().

* Voir aussi la page de documentation de Tasks.


Files d'attente
===============

Les files d'attente doivent être utilisées pour répartir le travail
entre plusieurs tâches asynchrones, implémenter des pools de
connexions et des modèles *pub*/*sub*.

+----------------------------------------------------+----------------------------------------------------+
| "Queue"                                            | File d'attente FIFO (premier entré, premier        |
|                                                    | sorti).                                            |
+----------------------------------------------------+----------------------------------------------------+
| "PriorityQueue"                                    | File d'attente avec gestion des priorités.         |
+----------------------------------------------------+----------------------------------------------------+
| "LifoQueue"                                        | Pile LIFO (dernier entré, premier sorti).          |
+----------------------------------------------------+----------------------------------------------------+

-[ Exemples ]-

* Utilisation d'asyncio.Queue pour répartir la charge de travail entre
  plusieurs tâches.

* Voir aussi la page de documentation des Queues.


Sous-processus
==============

Utilitaires pour générer des sous-processus et exécuter des commandes
shell.

+----------------------------------------------------+----------------------------------------------------+
| "await" "create_subprocess_exec()"                 | Crée un sous-processus.                            |
+----------------------------------------------------+----------------------------------------------------+
| "await" "create_subprocess_shell()"                | Exécute une commande shell.                        |
+----------------------------------------------------+----------------------------------------------------+

-[ Exemples ]-

* Exécution d'une commande shell.

* Voir aussi la documentation des API subprocess.


Flux (*streams*)
================

API de haut niveau pour travailler avec les entrées-sorties réseau.

+----------------------------------------------------+----------------------------------------------------+
| "await" "open_connection()"                        | Établit une connexion TCP.                         |
+----------------------------------------------------+----------------------------------------------------+
| "await" "open_unix_connection()"                   | Établit une connexion sur un connecteur Unix.      |
+----------------------------------------------------+----------------------------------------------------+
| "await" "start_server()"                           | Démarre un serveur TCP.                            |
+----------------------------------------------------+----------------------------------------------------+
| "await" "start_unix_server()"                      | Démarre un serveur de socket Unix.                 |
+----------------------------------------------------+----------------------------------------------------+
| "StreamReader"                                     | Objet *async/await* de haut niveau pour recevoir   |
|                                                    | des données réseau.                                |
+----------------------------------------------------+----------------------------------------------------+
| "StreamWriter"                                     | Objet *async/await* de haut niveau pour envoyer    |
|                                                    | des données réseau.                                |
+----------------------------------------------------+----------------------------------------------------+

-[ Exemples ]-

* Exemple de client TCP.

* Voir aussi la documentation des API streams.


Synchronisation
===============

Primitives de synchronisation de type thread qui peuvent être
utilisées dans les tâches.

+----------------------------------------------------+----------------------------------------------------+
| "Lock"                                             | Verrou mutex.                                      |
+----------------------------------------------------+----------------------------------------------------+
| "Event"                                            | Objet événement.                                   |
+----------------------------------------------------+----------------------------------------------------+
| "Condition"                                        | Objet condition.                                   |
+----------------------------------------------------+----------------------------------------------------+
| "Semaphore"                                        | Sémaphore.                                         |
+----------------------------------------------------+----------------------------------------------------+
| "BoundedSemaphore"                                 | Sémaphore avec des bornes.                         |
+----------------------------------------------------+----------------------------------------------------+
| "Barrier"                                          | Objet barrière.                                    |
+----------------------------------------------------+----------------------------------------------------+

-[ Exemples ]-

* Utilisation d'asyncio.Event.

* Utilisation d'asyncio.Barrier.

* Voir aussi la documentation des primitives asyncio de
  synchronisation.


Exceptions
==========

+----------------------------------------------------+----------------------------------------------------+
| "asyncio.CancelledError"                           | Levée lorsqu'une tâche est annulée. Voir aussi     |
|                                                    | "Task.cancel()".                                   |
+----------------------------------------------------+----------------------------------------------------+
| "asyncio.BrokenBarrierError"                       | Levée lorsqu'une barrière est brisée. Voir aussi   |
|                                                    | "Barrier.wait()".                                  |
+----------------------------------------------------+----------------------------------------------------+

-[ Exemples ]-

* Utilisation de CancelledError pour exécuter le code sur la demande
  d'annulation.

* Voir aussi la liste complète des exceptions spécifiques asyncio.
