`queue.md`

181 строк · 18.2 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.7/library/queue.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`queue`](https://python-all.ru/3.7/library/queue.html#module-queue) – синхронизированный класс очереди89**Исходный код:** [Lib/queue.py](https://python-all.ru/src/3.7/Lib/queue.py)1011---1213Модуль [`queue`](https://python-all.ru/3.7/library/queue.html#module-queue) реализует очереди с несколькими производителями и потребителями. Он особенно полезен в многопоточном программировании, когда необходимо безопасно обмениваться данными между несколькими потоками. Класс [`Queue`](https://python-all.ru/3.7/library/queue.html#queue.Queue) в этом модуле реализует всю необходимую семантику блокировок. Он зависит от наличия поддержки потоков в Python; см. модуль [`threading`](https://python-all.ru/3.7/library/threading.html#module-threading).1415Модуль реализует три типа очередей, которые различаются только порядком, в котором извлекаются элементы. В очереди FIFO первые добавленные задачи извлекаются первыми. В очереди LIFO последний добавленный элемент извлекается первым (работает как стек). В очереди с приоритетом элементы хранятся отсортированными (с использованием модуля [`heapq`](https://python-all.ru/3.7/library/heapq.html#module-heapq)), и элемент с наименьшим значением извлекается первым.1617Внутри этих трёх типов очередей для временной блокировки конкурирующих потоков используются блокировки; однако они не рассчитаны на реентерабельность в пределах одного потока.1819Кроме того, модуль реализует «простой» тип очереди FIFO, [`SimpleQueue`](https://python-all.ru/3.7/library/queue.html#queue.SimpleQueue), чья реализация предоставляет дополнительные гарантии ценой меньшей функциональности.2021Модуль [`queue`](https://python-all.ru/3.7/library/queue.html#module-queue) определяет следующие классы и исключения:2223#### `class queue.Queue(maxsize=0)`2425Конструктор для очереди FIFO. *maxsize* – целое число, задающее верхний предел количества элементов, которые можно поместить в очередь. Вставка будет блокироваться, когда этот размер достигнут, пока элементы очереди не будут потреблены. Если *maxsize* меньше или равно нулю, размер очереди бесконечен.2627#### `class queue.LifoQueue(maxsize=0)`2829Конструктор для очереди LIFO. *maxsize* – целое число, задающее верхний предел количества элементов, которые можно поместить в очередь. Вставка будет блокироваться, когда этот размер достигнут, пока элементы очереди не будут потреблены. Если *maxsize* меньше или равно нулю, размер очереди бесконечен.3031#### `class queue.PriorityQueue(maxsize=0)`3233Конструктор для очереди с приоритетом. *maxsize* – целое число, задающее верхний предел количества элементов, которые можно поместить в очередь. Вставка будет блокироваться, когда этот размер достигнут, пока элементы очереди не будут потреблены. Если *maxsize* меньше или равно нулю, размер очереди бесконечен.3435Элементы с наименьшим значением извлекаются первыми (элемент с наименьшим значением – это тот, который возвращается `sorted(list(entries))[0]`). Типичный шаблон для элементов – кортеж вида: `(priority_number, data)`.3637Если элементы *data* несравнимы, данные можно обернуть в класс, который игнорирует элемент данных и сравнивает только номер приоритета:3839```python40from dataclasses import dataclass, field41from typing import Any4243@dataclass(order=True)44class PrioritizedItem:45    priority: int46    item: Any=field(compare=False)47```4849#### `class queue.SimpleQueue`5051Конструктор для неограниченной очереди FIFO. Простые очереди лишены расширенной функциональности, такой как отслеживание задач.5253Добавлено в версии 3.7.5455#### `exception queue.Empty`5657Исключение, возбуждаемое при вызове неблокирующего [`get()`](https://python-all.ru/3.7/library/queue.html#queue.Queue.get) (или [`get_nowait()`](https://python-all.ru/3.7/library/queue.html#queue.Queue.get_nowait)) на пустом объекте [`Queue`](https://python-all.ru/3.7/library/queue.html#queue.Queue).5859#### `exception queue.Full`6061Исключение, возбуждаемое при вызове неблокирующего [`put()`](https://python-all.ru/3.7/library/queue.html#queue.Queue.put) (или [`put_nowait()`](https://python-all.ru/3.7/library/queue.html#queue.Queue.put_nowait)) на полном объекте [`Queue`](https://python-all.ru/3.7/library/queue.html#queue.Queue).6263## Объекты очередей6465Объекты очередей ([`Queue`](https://python-all.ru/3.7/library/queue.html#queue.Queue), [`LifoQueue`](https://python-all.ru/3.7/library/queue.html#queue.LifoQueue) или [`PriorityQueue`](https://python-all.ru/3.7/library/queue.html#queue.PriorityQueue)) предоставляют описанные ниже открытые методы.6667#### `Queue.qsize()`6869Возвращает приблизительный размер очереди. Обратите внимание: qsize() \> 0 не гарантирует, что последующий вызов get() не заблокируется, равно как qsize() \< maxsize не гарантирует, что put() не заблокируется.7071#### `Queue.empty()`7273Возвращает `True`, если очередь пуста, и `False` в противном случае. Если empty() возвращает `True`, это не гарантирует, что последующий вызов put() не заблокируется. Аналогично, если empty() возвращает `False`, это не гарантирует, что последующий вызов get() не заблокируется.7475#### `Queue.full()`7677Возвращает `True`, если очередь заполнена, и `False` в противном случае. Если full() возвращает `True`, это не гарантирует, что последующий вызов get() не заблокируется. Аналогично, если full() возвращает `False`, это не гарантирует, что последующий вызов put() не заблокируется.7879#### `Queue.put(item, block=True, timeout=None)`8081Помещает *item* в очередь. Если необязательный аргумент *block* равен true, а *timeout* равен `None` (по умолчанию), блокирует при необходимости до появления свободного места. Если *timeout* – положительное число, блокирует не более *timeout* секунд и вызывает исключение [`Full`](https://python-all.ru/3.7/library/queue.html#queue.Full), если за это время свободное место не появилось. В противном случае (*block* равен false), помещает элемент в очередь, если свободное место доступно немедленно, иначе вызывает исключение [`Full`](https://python-all.ru/3.7/library/queue.html#queue.Full) (*timeout* в этом случае игнорируется).8283#### `Queue.put_nowait(item)`8485Эквивалентно `put(item, False)`.8687#### `Queue.get(block=True, timeout=None)`8889Удаляет и возвращает элемент из очереди. Если необязательный аргумент *block* равен true, а *timeout* равен `None` (по умолчанию), блокирует при необходимости до появления элемента. Если *timeout* – положительное число, блокирует не более *timeout* секунд и вызывает исключение [`Empty`](https://python-all.ru/3.7/library/queue.html#queue.Empty), если за это время элемент не появился. В противном случае (*block* равен false), возвращает элемент, если он доступен немедленно, иначе вызывает исключение [`Empty`](https://python-all.ru/3.7/library/queue.html#queue.Empty) (*timeout* в этом случае игнорируется).9091До версии 3.0 в системах POSIX и во всех версиях в Windows, если *block* равен true, а *timeout* равен `None`, эта операция переходит в непрерываемое ожидание на базовой блокировке. Это означает, что никакие исключения не могут возникнуть, и, в частности, SIGINT не вызовет [`KeyboardInterrupt`](https://python-all.ru/3.7/library/exceptions.html#KeyboardInterrupt).9293#### `Queue.get_nowait()`9495Эквивалентно `get(False)`.9697Предлагаются два метода для отслеживания того, были ли задачи, поставленные в очередь, полностью обработаны потоками-потребителями-демонами.9899#### `Queue.task_done()`100101Указывает, что ранее поставленная в очередь задача завершена. Используется потоками-потребителями очереди. Для каждого вызова [`get()`](https://python-all.ru/3.7/library/queue.html#queue.Queue.get), использованного для получения задачи, последующий вызов [`task_done()`](https://python-all.ru/3.7/library/queue.html#queue.Queue.task_done) сообщает очереди, что обработка задачи завершена.102103Если [`join()`](https://python-all.ru/3.7/library/queue.html#queue.Queue.join) в данный момент заблокирован, он возобновит работу, когда все элементы будут обработаны (то есть для каждого элемента, который был [`put()`](https://python-all.ru/3.7/library/queue.html#queue.Queue.put) в очередь, был получен вызов [`task_done()`](https://python-all.ru/3.7/library/queue.html#queue.Queue.task_done)).104105Возбуждает [`ValueError`](https://python-all.ru/3.7/library/exceptions.html#ValueError), если вызывается больше раз, чем было помещено элементов в очередь.106107#### `Queue.join()`108109Блокируется до тех пор, пока все элементы в очереди не будут получены и обработаны.110111Счётчик незавершённых задач увеличивается при добавлении элемента в очередь. Счётчик уменьшается, когда поток-потребитель вызывает [`task_done()`](https://python-all.ru/3.7/library/queue.html#queue.Queue.task_done), указывая, что элемент получен и вся работа над ним завершена. Когда счётчик незавершённых задач падает до нуля, [`join()`](https://python-all.ru/3.7/library/queue.html#queue.Queue.join) разблокируется.112113Пример ожидания завершения поставленных в очередь задач:114115```python116def worker():117    while True:118        item = q.get()119        if item is None:120            break121        do_work(item)122        q.task_done()123124q = queue.Queue()125threads = []126for i in range(num_worker_threads):127    t = threading.Thread(target=worker)128    t.start()129    threads.append(t)130131for item in source():132    q.put(item)133134# ожидать завершения всех задач135q.join()136137# остановить workers138for i in range(num_worker_threads):139    q.put(None)140for t in threads:141    t.join()142```143144## Объекты SimpleQueue145146Объекты [`SimpleQueue`](https://python-all.ru/3.7/library/queue.html#queue.SimpleQueue) предоставляют описанные ниже публичные методы.147148#### `SimpleQueue.qsize()`149150Возвращает приблизительный размер очереди. Обратите внимание, qsize() \> 0 не гарантирует, что последующий вызов get() не заблокируется.151152#### `SimpleQueue.empty()`153154Возвращает `True`, если очередь пуста, иначе `False`. Если empty() возвращает `False`, это не гарантирует, что последующий вызов get() не будет заблокирован.155156#### `SimpleQueue.put(item, block=True, timeout=None)`157158Помещает *элемент* в очередь. Метод никогда не блокируется и всегда выполняется успешно (за исключением возможных низкоуровневых ошибок, например, сбоя выделения памяти). Необязательные аргументы *block* и *timeout* игнорируются и предоставлены только для совместимости с [`Queue.put()`](https://python-all.ru/3.7/library/queue.html#queue.Queue.put).159160**Особенность реализации CPython:** Этот метод имеет реализацию на C, которая является реентерабельной. То есть вызов `put()` или `get()` может быть прерван другим вызовом `put()` в том же потоке без взаимоблокировки или повреждения внутреннего состояния очереди. Это делает его подходящим для использования в деструкторах, таких как методы `__del__` или колбэки [`weakref`](https://python-all.ru/3.7/library/weakref.html#module-weakref).161162#### `SimpleQueue.put_nowait(item)`163164Эквивалентно `put(item)`, предусмотрено для совместимости с [`Queue.put_nowait()`](https://python-all.ru/3.7/library/queue.html#queue.Queue.put_nowait).165166#### `SimpleQueue.get(block=True, timeout=None)`167168Удаляет элемент из очереди и возвращает его. Если необязательный аргумент *block* равен true, а *timeout* равен `None` (по умолчанию), при необходимости блокирует выполнение, пока элемент не станет доступен. Если *timeout* – положительное число, блокирует выполнение не более чем на *timeout* секунд и вызывает исключение [`Empty`](https://python-all.ru/3.7/library/queue.html#queue.Empty), если за это время элемент не появился. В противном случае (*block* равен false) возвращает элемент, если он доступен немедленно, иначе вызывает исключение [`Empty`](https://python-all.ru/3.7/library/queue.html#queue.Empty) (*timeout* в этом случае игнорируется).169170#### `SimpleQueue.get_nowait()`171172Эквивалентно `get(False)`.173174> **См. также**175>176> **Класс [`multiprocessing.Queue`](https://python-all.ru/3.7/library/multiprocessing.html#multiprocessing.Queue)**177>178> Класс очереди для использования в контексте многопроцессорной обработки (а не многопоточности).179>180> [`collections.deque`](https://python-all.ru/3.7/library/collections.html#collections.deque) – это альтернативная реализация неограниченных очередей с быстрыми атомарными операциями [`append()`](https://python-all.ru/3.7/library/collections.html#collections.deque.append) и [`popleft()`](https://python-all.ru/3.7/library/collections.html#collections.deque.popleft), которые не требуют блокировки.181