`queue.md`

213 строк · 21.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.13/library/queue.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `queue` – синхронизированный класс очереди89**Исходный код:** [Lib/queue.py](https://python-all.ru/src/3.13/Lib/queue.py)1011---1213Модуль `queue` реализует очереди с несколькими производителями и несколькими потребителями. Особенно полезно в многопоточном программировании, когда нужно безопасно обмениваться данными между несколькими потоками. Класс [`Queue`](https://python-all.ru/3.13/library/queue.html#queue.Queue) в этом модуле реализует всю необходимую семантику блокировок.1415Модуль реализует три типа очередей, различающихся только порядком извлечения элементов. В очереди FIFO первые добавленные задачи извлекаются первыми. В очереди LIFO последний добавленный элемент извлекается первым (работает как стек). В очереди с приоритетом элементы хранятся отсортированными (с помощью модуля [`heapq`](https://python-all.ru/3.13/library/heapq.html#module-heapq)), и элемент с наименьшим значением извлекается первым.1617Внутри этих трёх типов очередей для временной блокировки конкурирующих потоков используются блокировки; однако они не рассчитаны на реентерабельность в пределах одного потока.1819Кроме того, модуль реализует «простой» тип очереди FIFO, [`SimpleQueue`](https://python-all.ru/3.13/library/queue.html#queue.SimpleQueue), чья реализация предоставляет дополнительные гарантии ценой меньшей функциональности.2021Модуль `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Элементы с наименьшим значением извлекаются первыми (элемент с наименьшим значением – это тот, который вернула бы функция `min(entries)`). Обычно элементы представлены кортежем вида: `(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Простые очереди являются [обобщёнными](https://python-all.ru/3.13/library/typing.html#generics) по типу своих элементов.5455Добавлено в версии 3.7.5657#### `exception queue.Empty`5859Исключение, возбуждаемое при вызове неблокирующего [`get()`](https://python-all.ru/3.13/library/queue.html#queue.Queue.get) (или [`get_nowait()`](https://python-all.ru/3.13/library/queue.html#queue.Queue.get_nowait)) на пустом объекте [`Queue`](https://python-all.ru/3.13/library/queue.html#queue.Queue).6061#### `exception queue.Full`6263Исключение, возбуждаемое при вызове неблокирующего [`put()`](https://python-all.ru/3.13/library/queue.html#queue.Queue.put) (или [`put_nowait()`](https://python-all.ru/3.13/library/queue.html#queue.Queue.put_nowait)) на полном объекте [`Queue`](https://python-all.ru/3.13/library/queue.html#queue.Queue).6465#### `exception queue.ShutDown`6667Исключение, возбуждаемое при вызове [`put()`](https://python-all.ru/3.13/library/queue.html#queue.Queue.put) или [`get()`](https://python-all.ru/3.13/library/queue.html#queue.Queue.get) на объекте [`Queue`](https://python-all.ru/3.13/library/queue.html#queue.Queue), который был закрыт.6869Добавлено в версии 3.13.7071## Объекты очередей7273Объекты очередей ([`Queue`](https://python-all.ru/3.13/library/queue.html#queue.Queue), [`LifoQueue`](https://python-all.ru/3.13/library/queue.html#queue.LifoQueue) или [`PriorityQueue`](https://python-all.ru/3.13/library/queue.html#queue.PriorityQueue)) предоставляют описанные ниже открытые методы.7475#### `Queue.qsize()`7677Возвращает приблизительный размер очереди. Обратите внимание: qsize() \> 0 не гарантирует, что последующий вызов get() не заблокируется, равно как qsize() \< maxsize не гарантирует, что put() не заблокируется.7879#### `Queue.empty()`8081Возвращает `True`, если очередь пуста, и `False` в противном случае. Если empty() возвращает `True`, это не гарантирует, что последующий вызов put() не заблокируется. Аналогично, если empty() возвращает `False`, это не гарантирует, что последующий вызов get() не заблокируется.8283#### `Queue.full()`8485Возвращает `True`, если очередь заполнена, и `False` в противном случае. Если full() возвращает `True`, это не гарантирует, что последующий вызов get() не заблокируется. Аналогично, если full() возвращает `False`, это не гарантирует, что последующий вызов put() не заблокируется.8687#### `Queue.put(item, block=True, timeout=None)`8889Помещает *элемент* в очередь. Если необязательный аргумент *block* истинен и *timeout* равен `None` (по умолчанию), блокируется при необходимости до освобождения места. Если *timeout* – положительное число, блокируется не более чем на *timeout* секунд и возбуждает исключение [`Full`](https://python-all.ru/3.13/library/queue.html#queue.Full), если за это время место не освободилось. В противном случае (*block* ложен), помещает элемент в очередь, если место свободно немедленно, иначе возбуждает исключение `Full` (в этом случае *timeout* игнорируется).9091Вызывает [`ShutDown`](https://python-all.ru/3.13/library/queue.html#queue.ShutDown), если очередь была закрыта.9293#### `Queue.put_nowait(item)`9495Эквивалентно `put(item, block=False)`.9697#### `Queue.get(block=True, timeout=None)`9899Удаляет элемент из очереди и возвращает его. Если необязательный аргумент *block* равен true, а *timeout* равен `None` (по умолчанию), при необходимости блокирует выполнение, пока элемент не станет доступен. Если *timeout* – положительное число, блокирует выполнение не более чем на *timeout* секунд и вызывает исключение [`Empty`](https://python-all.ru/3.13/library/queue.html#queue.Empty), если за это время элемент не появился. В противном случае (*block* равен false) возвращает элемент, если он доступен немедленно, иначе вызывает исключение `Empty` (*timeout* в этом случае игнорируется).100101До версии 3.0 в системах POSIX и во всех версиях Windows, если *block* истинен и *timeout* равен `None`, эта операция переходит в непрерываемое ожидание на базовой блокировке. Это означает, что никакие исключения не могут возникнуть, и, в частности, SIGINT не вызовет [`KeyboardInterrupt`](https://python-all.ru/3.13/library/exceptions.html#KeyboardInterrupt).102103Возбуждает [`ShutDown`](https://python-all.ru/3.13/library/queue.html#queue.ShutDown), если очередь была закрыта и пуста, или если очередь была закрыта немедленно.104105#### `Queue.get_nowait()`106107Эквивалентно `get(False)`.108109Предлагаются два метода для отслеживания того, были ли задачи, поставленные в очередь, полностью обработаны потоками-потребителями-демонами.110111#### `Queue.task_done()`112113Указывает, что ранее поставленная в очередь задача завершена. Используется потоками-потребителями очереди. Для каждого вызова [`get()`](https://python-all.ru/3.13/library/queue.html#queue.Queue.get), использованного для получения задачи, последующий вызов `task_done()` сообщает очереди, что обработка задачи завершена.114115Если [`join()`](https://python-all.ru/3.13/library/queue.html#queue.Queue.join) в данный момент заблокирован, он возобновит работу, когда все элементы будут обработаны (то есть для каждого элемента, который был [`put()`](https://python-all.ru/3.13/library/queue.html#queue.Queue.put) в очередь, был получен вызов `task_done()`).116117Возбуждает [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError), если вызывается больше раз, чем было помещено элементов в очередь.118119#### `Queue.join()`120121Блокируется до тех пор, пока все элементы в очереди не будут получены и обработаны.122123Счётчик незавершённых задач увеличивается каждый раз, когда элемент добавляется в очередь. Счётчик уменьшается, когда поток-потребитель вызывает [`task_done()`](https://python-all.ru/3.13/library/queue.html#queue.Queue.task_done), чтобы указать, что элемент был получен и вся работа с ним завершена. Когда счетчик незавершённых задач падает до нуля, `join()` разблокируется.124125### Ожидание завершения задач126127Пример ожидания завершения поставленных в очередь задач:128129```python130import threading131import queue132133q = queue.Queue()134135def worker():136    while True:137        item = q.get()138        print(f'Working on {item}')139        print(f'Finished {item}')140        q.task_done()141142# Запустить рабочий поток.143threading.Thread(target=worker, daemon=True).start()144145# Отправить рабочему тридцать запросов задач.146for item in range(30):147    q.put(item)148149# Ожидать завершения всех задач.150q.join()151print('All work completed')152```153154### Завершение работы очередей155156Когда больше не нужны, объекты [`Queue`](https://python-all.ru/3.13/library/queue.html#queue.Queue) можно постепенно завершить до опустошения или немедленно остановить с помощью жёсткого завершения.157158#### `Queue.shutdown(immediate=False)`159160Переводит экземпляр [`Queue`](https://python-all.ru/3.13/library/queue.html#queue.Queue) в режим завершения работы.161162Очередь больше не может расти. Будущие вызовы [`put()`](https://python-all.ru/3.13/library/queue.html#queue.Queue.put) возбуждают [`ShutDown`](https://python-all.ru/3.13/library/queue.html#queue.ShutDown). Текущие заблокированные вызывающие `put()` будут разблокированы и возбудят `ShutDown` в ранее заблокированном потоке.163164Если *immediate* равен false (значение по умолчанию), очередь можно завершить нормально с помощью вызовов [`get()`](https://python-all.ru/3.13/library/queue.html#queue.Queue.get) для извлечения задач, которые уже были загружены.165166И если [`task_done()`](https://python-all.ru/3.13/library/queue.html#queue.Queue.task_done) вызывается для каждой оставшейся задачи, ожидающий вызов [`join()`](https://python-all.ru/3.13/library/queue.html#queue.Queue.join) будет разблокирован нормально.167168Как только очередь опустеет, последующие вызовы [`get()`](https://python-all.ru/3.13/library/queue.html#queue.Queue.get) будут возбуждать исключение [`ShutDown`](https://python-all.ru/3.13/library/queue.html#queue.ShutDown).169170Если *immediate* равен true, очередь завершается немедленно. Очередь опустошается полностью, и счётчик незавершённых задач уменьшается на количество извлечённых задач. Если незавершённых задач нет, вызывающие [`join()`](https://python-all.ru/3.13/library/queue.html#queue.Queue.join) разблокируются. Также блокированные вызывающие [`get()`](https://python-all.ru/3.13/library/queue.html#queue.Queue.get) разблокируются и возбудят исключение [`ShutDown`](https://python-all.ru/3.13/library/queue.html#queue.ShutDown), так как очередь пуста.171172Соблюдайте осторожность при использовании [`join()`](https://python-all.ru/3.13/library/queue.html#queue.Queue.join) с параметром *immediate*, установленным в true. Это разблокирует join, даже если над задачами не было проделано никакой работы, нарушая обычный инвариант ожидания завершения очереди.173174Добавлено в версии 3.13.175176## Объекты SimpleQueue177178Объекты [`SimpleQueue`](https://python-all.ru/3.13/library/queue.html#queue.SimpleQueue) предоставляют описанные ниже публичные методы.179180#### `SimpleQueue.qsize()`181182Возвращает приблизительный размер очереди. Обратите внимание, qsize() \> 0 не гарантирует, что последующий вызов get() не заблокируется.183184#### `SimpleQueue.empty()`185186Возвращает `True`, если очередь пуста, и `False` в противном случае. Если empty() возвращает `False`, это не гарантирует, что последующий вызов get() не заблокируется.187188#### `SimpleQueue.put(item, block=True, timeout=None)`189190Помещает *элемент* в очередь. Метод никогда не блокируется и всегда выполняется успешно (за исключением возможных низкоуровневых ошибок, например, сбоя выделения памяти). Необязательные аргументы *block* и *timeout* игнорируются и предоставлены только для совместимости с [`Queue.put()`](https://python-all.ru/3.13/library/queue.html#queue.Queue.put).191192**Особенность реализации CPython:** Этот метод имеет реализацию на C, которая является реентерабельной. То есть вызов `put()` или `get()` может быть прерван другим вызовом `put()` в том же потоке без взаимоблокировки или повреждения внутреннего состояния очереди. Это делает его подходящим для использования в деструкторах, таких как методы `__del__` или колбэки [`weakref`](https://python-all.ru/3.13/library/weakref.html#module-weakref).193194#### `SimpleQueue.put_nowait(item)`195196Эквивалентно `put(item, block=False)`, предусмотрено для совместимости с [`Queue.put_nowait()`](https://python-all.ru/3.13/library/queue.html#queue.Queue.put_nowait).197198#### `SimpleQueue.get(block=True, timeout=None)`199200Удаляет элемент из очереди и возвращает его. Если необязательный аргумент *block* равен true, а *timeout* равен `None` (по умолчанию), при необходимости блокирует выполнение, пока элемент не станет доступен. Если *timeout* – положительное число, блокирует выполнение не более чем на *timeout* секунд и вызывает исключение [`Empty`](https://python-all.ru/3.13/library/queue.html#queue.Empty), если за это время элемент не появился. В противном случае (*block* равен false) возвращает элемент, если он доступен немедленно, иначе вызывает исключение `Empty` (*timeout* в этом случае игнорируется).201202#### `SimpleQueue.get_nowait()`203204Эквивалентно `get(False)`.205206> **См. также**207>208> **Класс [`multiprocessing.Queue`](https://python-all.ru/3.13/library/multiprocessing.html#multiprocessing.Queue)**209>210> Класс очереди для использования в контексте многопроцессорной обработки (а не многопоточности).211>212> [`collections.deque`](https://python-all.ru/3.13/library/collections.html#collections.deque) – это альтернативная реализация неограниченных очередей с быстрыми атомарными операциями [`append()`](https://python-all.ru/3.13/library/collections.html#collections.deque.append) и [`popleft()`](https://python-all.ru/3.13/library/collections.html#collections.deque.popleft), которые не требуют блокировок и также поддерживают индексирование.213