queue — clase de cola sincronizada

Código fuente: Lib/queue.py

El módulo queue implementa colas multi-productor y multi-consumidor. Es especialmente útil en la programación en hilo cuando la información debe intercambiarse de forma segura entre varios subprocesos. La clase Queue de este módulo implementa toda la semántica de bloqueo necesaria.

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.

Internamente, estos tres tipos de colas utilizan bloqueos para bloquear temporalmente los hilos que compiten entre sí; sin embargo, no están diseñadas para manejar la reposición dentro de un hilo.

Además, el módulo implementa un tipo de cola «simple» FIFO, SimpleQueue, cuya implementación específica proporciona garantías adicionales a cambio de una funcionalidad menor.

El módulo queue define las siguientes clases y excepciones:

class queue.Queue(maxsize=0)

Constructor para una cola FIFO. maxsize es un número entero que establece el límite superior del número de elementos que pueden ser colocados en la cola. La inserción se bloqueará una vez que se haya alcanzado este tamaño, hasta que se consuman los elementos de la cola. Si maxsize es menor o igual a cero, el tamaño de la cola es infinito.

class queue.LifoQueue(maxsize=0)

Constructor para una cola LIFO. maxsize es un número entero que establece el límite superior del número de elementos que pueden ser colocados en la cola. La inserción se bloqueará una vez que se haya alcanzado este tamaño, hasta que se consuman los elementos de la cola. Si maxsize es menor o igual a cero, el tamaño de la cola es infinito.

class queue.PriorityQueue(maxsize=0)

Constructor para una cola de prioridad. maxsize es un número entero que establece el límite superior del número de elementos que pueden ser colocados en la cola. La inserción se bloqueará una vez que se haya alcanzado este tamaño, hasta que se consuman los elementos de la cola. Si maxsize es menor o igual a cero, el tamaño de la cola es infinito.

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 los elementos de datos no son comparables, los datos pueden envolverse en una clase que ignore el elemento de datos y sólo compare el número de prioridad:

from dataclasses import dataclass, field
from typing import Any

@dataclass(order=True)
class PrioritizedItem:
    priority: int
    item: Any=field(compare=False)
class queue.SimpleQueue

Constructor de una cola sin límites FIFO. Las colas simples carecen de funcionalidad avanzada como el seguimiento de tareas.

Nuevo en la versión 3.7.

exception queue.Empty

Excepción lanzada cuando el objeto get() (o get_nowait()) que no se bloquea es llamado en un objeto Queue que está vacío.

exception queue.Full

Excepción lanzada cuando el objeto put() (o put_nowait()) que no se bloquea es llamado en un objeto Queue que está lleno.

Objetos de la cola

Los objetos de la cola (Queue, LifoQueue, o PriorityQueue) proporcionan los métodos públicos descritos a continuación.

Queue.qsize()

Retorna el tamaño aproximado de la cola. Nota, qsize() > 0 no garantiza que un get() posterior no se bloquee, ni qsize() < maxsize garantiza que put() no se bloquee.

Queue.empty()

Retorna True si la cola está vacía, False si no. Si empty() retorna True no garantiza que una llamada posterior a put() no se bloquee. Del mismo modo, si empty() retorna False no garantiza que una llamada posterior a get() no se bloquee.

Queue.full()

Retorna True si la cola está llena, False si no. Si full() retorna True no garantiza que una llamada posterior a get() no se bloquee. Del mismo modo, si full() retorna False no garantiza que una llamada posterior a put() no se bloquee.

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

Queue.put_nowait(item)

Equivalent to put(item, block=False).

Queue.get(block=True, timeout=None)

Retira y retorna un elemento de la cola. Si los argumentos opcionales block son true y timeout es None (el predeterminado), bloquea si es necesario hasta que un elemento esté disponible. Si timeout es un número positivo, bloquea como máximo timeout segundos y lanza la excepción Empty si no había ningún elemento disponible en ese tiempo. De lo contrario (block es falso), retorna un elemento si uno está disponible inmediatamente, o bien lanza la excepción Empty (timeout es ignorado en ese caso).

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.

Queue.get_nowait()

Equivalente a get(False).

Se ofrecen dos métodos para apoyar el seguimiento si las tareas en cola han sido completamente procesadas por hilos daemon de consumo.

Queue.task_done()

Indica que una tarea anteriormente en cola está completa. Utilizado por los hilos de la cola de consumo. Por cada get() usado para recuperar una tarea, una llamada posterior a task_done() le dice a la cola que el procesamiento de la tarea está completo.

Si un join() se está bloqueando actualmente, se reanudará cuando todos los ítems hayan sido procesados (lo que significa que se recibió una llamada task_done() por cada ítem que había sido put() en la cola).

Lanza un ValueError si se llama más veces de las que hay elementos colocados en la cola.

Queue.join()

Bloquea hasta que todos los artículos de la cola se hayan obtenido y procesado.

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.

Ejemplo de cómo esperar a que se completen las tareas en cola:

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

Objetos de cola simple

Los objetos SimpleQueue proporcionan los métodos públicos descritos a continuación.

SimpleQueue.qsize()

Retorna el tamaño aproximado de la cola. Nota, qsize() > 0 no garantiza que un get() posterior no se bloquee.

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)

Pone el elemento en la cola. El método nunca se bloquea y siempre tiene éxito (excepto por posibles errores de bajo nivel como la falta de asignación de memoria). Los argumentos opcionales block y timeout son ignorados y sólo se proporcionan por compatibilidad con Queue.put().

Detalles de implementación de 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)

Retira y retorna un elemento de la cola. Si los argumentos opcionales block son true y timeout es None (el predeterminado), bloquea si es necesario hasta que un elemento esté disponible. Si timeout es un número positivo, bloquea como máximo timeout segundos y lanza la excepción Empty si no había ningún elemento disponible en ese tiempo. De lo contrario (block es falso), retorna un elemento si uno está disponible inmediatamente, o bien lanza la excepción Empty (timeout es ignorado en ese caso).

SimpleQueue.get_nowait()

Equivalente a get(False).

Ver también

Clase multiprocessing.Queue

Una clase de cola para su uso en un contexto de multiprocesamiento (en lugar de multihilo).

collections.deque es una implementación alternativa de colas sin límites con operaciones atómicas rápidas append() y popleft() que no requieren bloqueo y también soportan indexación.