8.10. "Queue" — A synchronized queue class
******************************************

Note: The "Queue" module has been renamed to "queue" in Python 3.
  The *2to3* tool will automatically adapt imports when converting
  your sources to Python 3.

**Source code:** Lib/Queue.py

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

The "Queue" module implements multi-producer, multi-consumer queues.
It is especially useful in threaded programming when information must
be exchanged safely between multiple threads.  The "Queue" class in
this module implements all the required locking semantics.  It depends
on the availability of thread support in Python; see the "threading"
module.

The module implements three types of queue, which differ only in the
order in which the entries are retrieved.  In a FIFO queue, the first
tasks added are the first retrieved. In a LIFO queue, the most
recently added entry is the first retrieved (operating like a stack).
With a priority queue, the entries are kept sorted (using the "heapq"
module) and the lowest valued entry is retrieved first.

The "Queue" module defines the following classes and exceptions:

class Queue.Queue(maxsize=0)

   Constructor for a FIFO queue.  *maxsize* is an integer that sets
   the upperbound limit on the number of items that can be placed in
   the queue.  Insertion will block once this size has been reached,
   until queue items are consumed.  If *maxsize* is less than or equal
   to zero, the queue size is infinite.

class Queue.LifoQueue(maxsize=0)

   Constructor for a LIFO queue.  *maxsize* is an integer that sets
   the upperbound limit on the number of items that can be placed in
   the queue.  Insertion will block once this size has been reached,
   until queue items are consumed.  If *maxsize* is less than or equal
   to zero, the queue size is infinite.

   Nouveau dans la version 2.6.

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

   Nouveau dans la version 2.6.

exception Queue.Empty

   Exception raised when non-blocking "get()" (or "get_nowait()") is
   called on a "Queue" object which is empty.

exception Queue.Full

   Exception raised when non-blocking "put()" (or "put_nowait()") is
   called on a "Queue" object which is full.

Voir aussi: "collections.deque" is an alternative implementation of
  unbounded queues with fast atomic "append()" and "popleft()"
  operations that do not require locking.


8.10.1. Objets "Queue"
======================

Queue objects ("Queue", "LifoQueue", or "PriorityQueue") provide the
public methods described below.

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[, timeout]])

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

   Nouveau dans la version 2.3: The *timeout* parameter.

Queue.put_nowait(item)

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

Queue.get([block[, timeout]])

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

   Nouveau dans la version 2.3: The *timeout* parameter.

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.

   Nouveau dans la version 2.5.

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.

   Nouveau dans la version 2.5.

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

   def worker():
       while True:
           item = q.get()
           do_work(item)
           q.task_done()

   q = Queue()
   for i in range(num_worker_threads):
        t = Thread(target=worker)
        t.daemon = True
        t.start()

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

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