queue — класс синхронизированной очереди

Объекты очереди

Объекты очередей (Queue, LifoQueue или PriorityQueue) предоставляют описанные ниже общедоступные методы.

Queue.qsize()

Возвращает приблизительный размер очереди. Обратите внимание: qsize() > 0 не гарантирует, что последующий вызов get() не будет заблокирован; также qsize() < maxsize не гарантирует, что put() не будет заблокирован.

Queue.empty()

Возвращает True, если очередь пуста, и False в противном случае. Если empty() возвращает True, это не гарантирует, что последующий вызов put() не будет заблокирован. Аналогично, если empty() возвращает False, это не гарантирует, что последующий вызов get() не будет заблокирован.

Queue.full()

Возвращает True, если очередь заполнена, и False в противном случае. Если full() возвращает True, это не гарантирует, что последующий вызов get() не будет заблокирован. Аналогично, если full() возвращает False, это не гарантирует, что последующий вызов put() не будет заблокирован.

Queue.put(item, block=True, timeout=None)

Помещает item в очередь. Если необязательный аргумент block имеет значение true, а аргумент timeout равен None (значение по умолчанию), при необходимости блокирует выполнение до появления свободного места. Если timeout — положительное число, метод блокируется не более чем на timeout секунд и возбуждает исключение Full, если за это время свободное место не появилось. В противном случае (если block имеет значение false) элемент помещается в очередь, если свободное место доступно немедленно; иначе возбуждается исключение Full (в этом случае аргумент timeout игнорируется).

Возбуждает исключение ShutDown, если очередь отключена.

Queue.put_nowait(item)

Эквивалентен put(item, block=False).

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

Извлекает элемент из очереди и возвращает его. Если необязательный аргумент block имеет значение true, а аргумент timeout равен None (значение по умолчанию), при необходимости блокирует выполнение до появления элемента. Если timeout — положительное число, метод блокируется не более чем на timeout секунд и возбуждает исключение Empty, если за это время элемент не появился. В противном случае (если block имеет значение false) возвращает элемент, если он доступен немедленно; иначе возбуждает исключение Empty (в этом случае аргумент timeout игнорируется).

До версии 3.0 в системах POSIX, а также во всех версиях Windows, если block имеет значение true, а timeout равен None, эта операция переводит поток в непрерываемое ожидание на базовой блокировке. Это означает, что исключения не могут возникнуть; в частности, SIGINT не вызовет исключение KeyboardInterrupt.

Возбуждает исключение ShutDown, если очередь отключена и пуста либо если очередь отключена немедленно.

Queue.get_nowait()

Эквивалентен get(False).

Для отслеживания полной обработки поставленных в очередь задач потоками-потребителями предусмотрены два метода.

Queue.task_done()

Сообщает, что ранее поставленная в очередь задача выполнена. Используется потоками-потребителями очереди. Для каждого вызова get(), использованного для получения задачи, последующий вызов task_done() сообщает очереди, что обработка задачи завершена.

Если в данный момент выполняется блокирующий вызов join(), он возобновится после обработки всех элементов (то есть после получения вызова task_done() для каждого элемента, который был помещён в очередь с помощью put()).

Возбуждает исключение ValueError, если вызвано больше раз, чем элементов было помещено в очередь.

Queue.join()

Блокирует выполнение до извлечения и обработки всех элементов очереди.

Счётчик незавершённых задач увеличивается каждый раз, когда элемент добавляется в очередь. Счётчик уменьшается каждый раз, когда поток-потребитель вызывает task_done(), сообщая, что элемент был извлечён и вся работа с ним завершена. Когда счётчик незавершённых задач достигает нуля, блокировка join() снимается.

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

Объекты SimpleQueue

Объекты SimpleQueue предоставляют описанные ниже общедоступные методы.

SimpleQueue.qsize()

Возвращает приблизительный размер очереди. Обратите внимание: qsize() > 0 не гарантирует, что последующий вызов get() не будет заблокирован.

SimpleQueue.empty()

Возвращает True, если очередь пуста, и False в противном случае. Если empty() возвращает False, это не гарантирует, что последующий вызов get() не будет заблокирован.

SimpleQueue.put(item, block=True, timeout=None)

Помещает item в очередь. Метод никогда не блокируется и всегда выполняется успешно (за исключением возможных низкоуровневых ошибок, например невозможности выделить память). Необязательные аргументы block и timeout игнорируются и предусмотрены только для совместимости с Queue.put().

Особенность реализации CPython: Этот метод реализован на C и допускает повторный вход. То есть вызов put() или get() может быть прерван другим вызовом put() в том же потоке без взаимной блокировки и нарушения внутреннего состояния очереди. Благодаря этому метод подходит для использования в деструкторах, например в методах __del__, или в обратных вызовах weakref.

SimpleQueue.put_nowait(item)

Эквивалентен put(item, block=False) и предусмотрен для совместимости с Queue.put_nowait().

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

Извлекает элемент из очереди и возвращает его. Если необязательный аргумент block имеет значение true, а аргумент timeout равен None (значение по умолчанию), при необходимости блокирует выполнение до появления элемента. Если timeout — положительное число, метод блокируется не более чем на timeout секунд и возбуждает исключение Empty, если за это время элемент не появился. В противном случае (если block имеет значение false) возвращает элемент, если он доступен немедленно; иначе возбуждает исключение Empty (в этом случае аргумент timeout игнорируется).

SimpleQueue.get_nowait()

Эквивалентен get(False).