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
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.
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.
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. 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()
(ouget_nowait()
) est appelée sur l'objetQueue
vide.
- exception queue.Full¶
Exception levée lorsque la méthode non bloquante
put()
(ouput_nowait()
) est appelée sur un objetQueue
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'unget()
ultérieur ne sera pas bloquant et queqsize() < maxsize
ne garantit pas non plus qu'unput()
ne sera pas bloquant.
- Queue.empty()¶
Renvoie
True
si la file est vide,False
sinon. Siempty()
renvoieTrue
, cela ne garantit pas qu'un appel ultérieur àput()
ne sera pas bloquant. Similairement, siempty()
renvoieFalse
, 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. Sifull()
renvoieTrue
, cela ne garantit pas qu'un appel ultérieur àget()
ne sera pas bloquant. Similairement, sifull()
retourneFalse
, 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 theFull
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 theFull
exception (timeout is ignored in that case).
- 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
etNone
(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'exceptionEmpty
s'il n'y avait pas d'élément disponible pendant cette période de temps. Sinon (block vautFalse
), 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'exceptionEmpty
(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 aKeyboardInterrupt
.
- 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.
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')
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'unget()
ultérieur ne soit pas bloquant.
- SimpleQueue.empty()¶
Return
True
if the queue is empty,False
otherwise. If empty() returnsFalse
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()
orget()
call can be interrupted by anotherput()
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 orweakref
callbacks.
- SimpleQueue.put_nowait(item)¶
Equivalent to
put(item, block=False)
, provided for compatibility withQueue.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
etNone
(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'exceptionEmpty
s'il n'y avait pas d'élément disponible pendant cette période de temps. Sinon (block vautFalse
), 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'exceptionEmpty
(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.