17.7. "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, le module utilise des verrous pour bloquer temporairement
des fils d'exécution concurrents. Cependant, il n'a pas été conçu pour
être réentrant au sein d'un fil d'exécution.

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

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.


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

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()

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.
