# 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