"queue" — File synchronisée
***************************

**Code source :** Lib/queue.py

======================================================================

Le module "queue" implémente des files multi-productrices et multi-
consommatrices. C'est particulièrement utile en programmation *multi-
thread*, lorsque les informations doivent être échangées sans risques
entre plusieurs *threads*. La classe "Queue" de ce module implémente
tout le verrouillage nécessaire. Cela dépend de la disponibilité du
support des fils d'exécution en Python; voir le module "threading".

Le module implémente trois types de files qui différent par l'ordre
dans lequel les éléments en sont extraits. Dans une file FIFO (first-
in, first-out), les premiers éléments ajoutés sont les premiers
extraits. Dans une file LIFO (last-in, first-out), le dernier élément
ajouté est le premier élément extrait (se comporte comme une pile).
Avec une file de priorité, les entrées restent triés (en utilisant le
module "heapq")  et l'élément ayant la valeur la plus faible est
extrait en premier.

En interne, ces trois types de files utilisent des verrous pour
bloquer temporairement des fils d'exécution concurrents. Cependant,
ils n'ont pas été conçus pour être réentrants au sein d'un fil
d'exécution.

Le module implémente aussi une FIFO (first-in, first-out) basique,
"SimpleQueue", dont l’implémentation spécialisée fournit plus de
garanties au détriment des fonctionnalités.

Le module "queue" définit les classes et les exceptions suivantes :

class queue.Queue(maxsize=0)

   Constructeur pour une file FIFO (first-in, first-out). *maxsize*
   est un entier définissant le nombre maximal d'éléments pouvant être
   mis dans la file. L'insertion sera bloquée lorsque cette borne
   supérieure sera atteinte, jusqu'à ce que des éléments de la file
   soient consommés. Si *maxsize* est inférieur ou égal à 0, la taille
   de la file sera infinie.

class queue.LifoQueue(maxsize=0)

   Constructeur pour une file LIFO (last-in, first-out). *maxsize* est
   un entier définissant le nombre maximal d'éléments pouvant être mis
   dans la file. L'insertion sera bloquée lorsque cette borne
   supérieure sera atteinte, jusqu'à ce que des éléments de la file
   soient consommés. Si *maxsize* est inférieur ou égal à 0, la taille
   de la file sera infinie.

class queue.PriorityQueue(maxsize=0)

   Constructeur pour une file de priorité. *maxsize* est un entier
   définissant le nombre maximal d'éléments pouvant être mis dans la
   file. L'insertion sera bloquée lorsque cette borne supérieure sera
   atteinte, jusqu'à ce que des éléments soient consommés. Si
   *maxsize* est inférieur ou égal à 0, la taille de la file sera
   infinie.

   Les éléments de valeurs les plus faibles sont extraits en premier
   (l'élément de valeur la plus faible est celui renvoyé par
   "sorted(list(entries))[0]"). Un cas typique est d'utiliser des
   tuple de la forme : "(priority_number, data)".

   Si les éléments de *data* ne sont pas comparables, les données
   peuvent être enveloppées dans une classe qui ignore l'élément de
   données et ne compare que l'ordre de priorité :

      from dataclasses import dataclass, field
      from typing import Any

      @dataclass(order=True)
      class PrioritizedItem:
          priority: int
          item: Any=field(compare=False)

class queue.SimpleQueue

   Constructeur d'une file illimitée FIFO (first-in, first-out). Les
   simples files d'attente ne possèdent pas de fonctionnalités
   avancées telles que le suivi des tâches.

   Nouveau dans la version 3.7.

exception queue.Empty

   Exception levée lorsque la méthode non bloquante "get()" (ou
   "get_nowait()") est appelée sur l'objet "Queue" vide.

exception queue.Full

   Exception levée lorsque la méthode non bloquante "put()" (ou
   "put_nowait()") est appelée sur un objet "Queue" plein.


Objets "Queue"
==============

Les objets *Queue* ("Queue", "LifoQueue" ou "PriorityQueue")
fournissent les méthodes publiques décrites ci-dessous.

Queue.qsize()

   Renvoie la taille approximative de la file.  Notez que "qsize() >
   0" ne garantit pas qu'un "get()" ultérieur ne sera pas bloquant et
   que "qsize() < maxsize" ne garantit pas non plus qu'un "put()" ne
   sera pas bloquant.

Queue.empty()

   Renvoie "True" si la file est vide, "False" sinon.  Si "empty()"
   renvoie "True", cela ne garantit pas qu'un appel ultérieur à
   "put()" ne sera pas bloquant.  Similairement, si "empty()" renvoie
   "False", cela ne garantit pas qu'un appel ultérieur à "get()" ne
   sera pas bloquant.

Queue.full()

   Renvoie "True" si la file est pleine, "False" sinon.  Si "full()"
   renvoie``True``, cela ne garantit pas qu'un appel ultérieur à
   "get()" ne sera pas bloquant.  Similairement, si "full()" retourne
   "False", cela ne garantit pas qu'un appel ultérieur à "put()" ne
   sera pas bloquant.

Queue.put(item, block=True, timeout=None)

   Met *item* dans la file. Si les arguments optionnels *block* et
   *timeout* sont respectivement "True" et "None" (les valeurs par
   défaut), la méthode bloque si nécessaire jusqu'à ce qu'un
   emplacement libre soit disponible. Si *timeout* est un nombre
   positif, elle bloque au plus *timeout* secondes et lève l'exception
   "Full" s'il n'y avait pas d'emplacement libre pendant cette période
   de temps. Sinon (*block* est "False"), elle met un élément dans la
   file s'il y a un emplacement libre immédiatement disponible. Si ce
   n'est pas le cas, elle lève l'exception "Full" (*timeout* est
   ignoré dans ce cas).

Queue.put_nowait(item)

   Équivalent à "put(item, False)".

Queue.get(block=True, timeout=None)

   Retire et renvoie un élément de la file. Si les arguments
   optionnels *block* et *timeout* valent respectivement "True" et
   "None" (les valeurs par défaut), la méthode bloque si nécessaire
   jusqu'à ce qu'un élément soit disponible. Si *timeout* est un
   entier positif, elle bloque au plus *timeout* secondes et lève
   l'exception "Empty" s'il n'y avait pas d'élément disponible pendant
   cette période de temps. Sinon (*block* vaut "False"), elle renvoie
   un élément s'il y en a un immédiatement disponible. Si ce n'est pas
   le cas, elle lève l'exception "Empty" (*timeout* est ignoré dans ce
   cas).

   Avant Python 3.0 sur les systèmes POSIX, et pour toutes les
   versions sur Windows, si *block* est vrai et *timeout* vaut "None",
   cette opération rentre dans une attente ininterruptible sous un
   verrou. Cela veut dire qu'aucune exception ne peut arriver et, en
   particulier, un *SIGINT* ne déclenchera pas de "KeyboardInterrupt".

Queue.get_nowait()

   Équivalent à "get(False)".

Deux méthodes sont proposées afin de savoir si les tâches mises dans
la file ont été entièrement traitées par les fils d'exécution
consommateurs du démon.

Queue.task_done()

   Indique qu'une tâche précédemment mise dans la file est terminée.
   Utilisé par les fils d'exécution consommateurs de la file. Pour
   chaque appel à "get()" effectué afin de récupérer une tâche, un
   appel ultérieur à "task_done()" informe la file que le traitement
   de la tâche est terminé.

   Si un "join()" est actuellement bloquant, on reprendra lorsque tous
   les éléments auront été traités (ce qui signifie qu'un appel à
   "task_done()" a été effectué pour chaque élément qui a été "put()"
   dans la file).

   Lève une exception "ValueError" si appelée plus de fois qu'il y
   avait d'éléments dans la file.

Queue.join()

   Bloque jusqu'à ce que tous les éléments de la file aient été
   obtenus et traités.

   Le nombre de tâches inachevées augmente chaque fois qu'un élément
   est ajouté à la file. Ce nombre diminue chaque fois qu'un fil
   d'exécution consommateur appelle "task_done()" pour indiquer que
   l'élément a été extrait et que tout le travail à effectuer dessus
   est terminé. Lorsque le nombre de tâches non terminées devient nul,
   "join()" débloque.

Exemple montrant comment attendre que les tâches mises dans la file
soient terminées :

   def worker():
       while True:
           item = q.get()
           if item is None:
               break
           do_work(item)
           q.task_done()

   q = queue.Queue()
   threads = []
   for i in range(num_worker_threads):
       t = threading.Thread(target=worker)
       t.start()
       threads.append(t)

   for item in source():
       q.put(item)

   # block until all tasks are done
   q.join()

   # stop workers
   for i in range(num_worker_threads):
       q.put(None)
   for t in threads:
       t.join()


Objets "SimpleQueue"
====================

Les objets "SimpleQueue" fournissent les méthodes publiques décrites
ci-dessous.

SimpleQueue.qsize()

   Renvoie la taille approximative de la file. Notez que "qsize() > 0"
   ne garantit pas qu'un "get()" ultérieur ne soit pas bloquant.

SimpleQueue.empty()

   Renvoie "True" si la file est vide, "False" sinon. Si "empty()"
   renvoie "False", cela ne garantit pas qu'un appel ultérieur à
   "get()" ne soit pas bloquant.

SimpleQueue.put(item, block=True, timeout=None)

   Met *item* dans la file. La méthode ne bloque jamais et aboutit
   toujours (sauf en cas de potentielles erreurs de bas niveau, telles
   qu'un échec d'allocation de mémoire). Les arguments optionnels
   *block* et *timeout* sont ignorés et fournis uniquement pour la
   compatibilité avec "Queue.put()".

   **CPython implementation detail:** This method has a C
   implementation which is reentrant.  That is, a "put()" or "get()"
   call can be interrupted by another "put()" call in the same thread
   without deadlocking or corrupting internal state inside the queue.
   This makes it appropriate for use in destructors such as "__del__"
   methods or "weakref" callbacks.

SimpleQueue.put_nowait(item)

   Équivalent de "put(item)", fourni pour la compatibilité avec
   "Queue.put_nowait()".

SimpleQueue.get(block=True, timeout=None)

   Retire et renvoie un élément de la file. Si les arguments
   optionnels *block* et *timeout* valent respectivement "True" et
   "None" (les valeurs par défaut), la méthode bloque si nécessaire
   jusqu'à ce qu'un élément soit disponible. Si *timeout* est un
   entier positif, elle bloque au plus *timeout* secondes et lève
   l'exception "Empty" s'il n'y avait pas d'élément disponible pendant
   cette période de temps. Sinon (*block* vaut "False"), elle renvoie
   un élément s'il y en a un immédiatement disponible. Si ce n'est pas
   le cas, elle lève l'exception "Empty" (*timeout* est ignoré dans ce
   cas).

SimpleQueue.get_nowait()

   Équivalent à "get(False)".

Voir aussi:

  Classe "multiprocessing.Queue"
     Une file à utiliser dans un contexte multi-processus (plutôt que
     *multi-thread*).

  "collections.deque" est une implémentation alternative de file non
  bornée avec des méthodes "append()" et "popleft()" rapides et
  atomiques ne nécessitant pas de verrouillage.
