Ce document est relatif à une vieille version de Python qui n'est plus soutenue. Mettez à jour votre version et lisez Bienvenue sur la documentation de la version stable actuelle de Python.

# `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, les premiers éléments ajoutés sont les premiers extraits. Dans une file LIFO, 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 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. 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. 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. 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.