"queue" --- A synchronized queue class
**************************************

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

The module implements three types of queue, which differ only in the
order in which the entries are retrieved.  In a FIFO (first-in, first-
out) queue, the first tasks added are the first retrieved.  In a LIFO
(last-in, first-out) 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.

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.

   The lowest valued entries are retrieved first (the lowest valued
   entry is the one that would be returned by "min(entries)").  A
   typical pattern for entries is a tuple in the form:
   "(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.

   Ajouté 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.

exception queue.ShutDown

   Exception raised when "put()" or "get()" is called on a "Queue"
   object which has been shut down.

   Ajouté dans la version 3.13.


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)

   Put *item* into the queue.  If optional args *block* is true and
   *timeout* is "None" (the default), block if necessary until a free
   slot is available.  If *timeout* is a positive number, it blocks at
   most *timeout* seconds and raises the "Full" exception if no free
   slot was available within that time. Otherwise (*block* is false),
   put an item on the queue if a free slot is immediately available,
   else raise the "Full" exception (*timeout* is ignored in that
   case).

   Raises "ShutDown" if the queue has been shut down.

Queue.put_nowait(item)

   Equivalent to "put(item, block=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).

   Prior to 3.0 on POSIX systems, and for all versions on Windows, if
   *block* is true and *timeout* is "None", this operation goes into
   an uninterruptible wait on an underlying lock.  This means that no
   exceptions can occur, and in particular a SIGINT will not trigger a
   "KeyboardInterrupt".

   Raises "ShutDown" if the queue has been shut down and is empty, or
   if the queue has been shut down immediately.

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.

   The count of unfinished tasks goes up whenever an item is added to
   the queue. The count goes down whenever a consumer thread calls
   "task_done()" to indicate that the item was retrieved and all work
   on it is complete.  When the count of unfinished tasks drops to
   zero, "join()" unblocks.


Waiting for task completion
---------------------------

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

   import threading
   import queue

   q = queue.Queue()

   def worker():
       while True:
           item = q.get()
           print(f'Working on {item}')
           print(f'Finished {item}')
           q.task_done()

   # Turn-on the worker thread.
   threading.Thread(target=worker, daemon=True).start()

   # Send thirty task requests to the worker.
   for item in range(30):
       q.put(item)

   # Block until all tasks are done.
   q.join()
   print('All work completed')


Terminating queues
------------------

When no longer needed, "Queue" objects can be wound down until empty
or terminated immediately with a hard shutdown.

Queue.shutdown(immediate=False)

   Put a "Queue" instance into a shutdown mode.

   The queue can no longer grow. Future calls to "put()" raise
   "ShutDown". Currently blocked callers of "put()" will be unblocked
   and will raise "ShutDown" in the formerly blocked thread.

   If *immediate* is false (the default), the queue can be wound down
   normally with "get()" calls to extract tasks that have already been
   loaded.

   And if "task_done()" is called for each remaining task, a pending
   "join()" will be unblocked normally.

   Once the queue is empty, future calls to "get()" will raise
   "ShutDown".

   If *immediate* is true, the queue is terminated immediately. The
   queue is drained to be completely empty.  All callers of "join()"
   are unblocked regardless of the number of unfinished tasks.
   Blocked callers of "get()" are unblocked and will raise "ShutDown"
   because the queue is empty.

   Use caution when using "join()" with *immediate* set to true. This
   unblocks the join even when no work has been done on the tasks,
   violating the usual invariant for joining a queue.

   Ajouté dans la version 3.13.


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

   Return "True" if the queue is empty, "False" otherwise.  If empty()
   returns "False" it doesn't guarantee that a subsequent call to
   get() will not block.

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

   **Particularité de l'implémentation CPython :** 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)

   Equivalent to "put(item, block=False)", provided for compatibility
   with "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 et prenant également en
  charge l'indexation.
