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 — истина, а timeout — None, заблокировать, если необходимо, пока не освободится место. Если timeout — положительное число, заблокировать не более timeout секунд и поднять исключение Full, если свободного места не было в течение этого времени. В противном случае (block — ложь), поместить элемент в очередь, если свободное место доступно немедленно, иначе поднять исключение Full (timeout игнорируется в этом случае).

Queue.put_nowait(item)

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

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

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

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

Queue.get_nowait()

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

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

Queue.task_done()

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

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

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

Queue.join()

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

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

Пример того, как дождаться завершения задач в очереди:

import threading, 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)
print('All task requests sent\n', end='')

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

Поместить элемент в очередь. Метод никогда не блокируется и всегда выполняется успешно (за исключением потенциальных ошибок низкого уровня, таких как невозможность выделения памяти). Необязательные аргументы 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).