`queue.md`

177 строк · 18.3 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.10/library/queue.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`queue`](https://python-all.ru/3.10/library/queue.html#module-queue) – синхронизированный класс очереди89**Исходный код:** [Lib/queue.py](https://python-all.ru/src/3.10/Lib/queue.py)1011---1213Модуль [`queue`](https://python-all.ru/3.10/library/queue.html#module-queue) реализует очереди с несколькими производителями и несколькими потребителями. Особенно полезно в многопоточном программировании, когда нужно безопасно обмениваться данными между несколькими потоками. Класс [`Queue`](https://python-all.ru/3.10/library/queue.html#queue.Queue) в этом модуле реализует всю необходимую семантику блокировок.1415Модуль реализует три типа очередей, различающихся только порядком извлечения элементов. В очереди FIFO первые добавленные задачи извлекаются первыми. В очереди LIFO последний добавленный элемент извлекается первым (работает как стек). В очереди с приоритетом элементы хранятся отсортированными (с помощью модуля [`heapq`](https://python-all.ru/3.10/library/heapq.html#module-heapq)), и элемент с наименьшим значением извлекается первым.1617Внутри этих трёх типов очередей для временной блокировки конкурирующих потоков используются блокировки; однако они не рассчитаны на реентерабельность в пределах одного потока.1819Кроме того, модуль реализует «простой» тип очереди FIFO, [`SimpleQueue`](https://python-all.ru/3.10/library/queue.html#queue.SimpleQueue), чья реализация предоставляет дополнительные гарантии ценой меньшей функциональности.2021Модуль [`queue`](https://python-all.ru/3.10/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Элементы с наименьшим значением извлекаются первыми (элемент с наименьшим значением – это тот, который вернула бы функция `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Добавлено в версии 3.7.5455#### `exception queue.Empty`5657Исключение, возбуждаемое при вызове неблокирующего [`get()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.get) (или [`get_nowait()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.get_nowait)) на пустом объекте [`Queue`](https://python-all.ru/3.10/library/queue.html#queue.Queue).5859#### `exception queue.Full`6061Исключение, возбуждаемое при вызове неблокирующего [`put()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.put) (или [`put_nowait()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.put_nowait)) на полном объекте [`Queue`](https://python-all.ru/3.10/library/queue.html#queue.Queue).6263## Объекты очередей6465Объекты очередей ([`Queue`](https://python-all.ru/3.10/library/queue.html#queue.Queue), [`LifoQueue`](https://python-all.ru/3.10/library/queue.html#queue.LifoQueue) или [`PriorityQueue`](https://python-all.ru/3.10/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Помещает *элемент* в очередь. Если необязательный аргумент *block* истинен и *timeout* равен `None` (по умолчанию), блокируется при необходимости до освобождения места. Если *timeout* – положительное число, блокируется не более чем на *timeout* секунд и возбуждает исключение [`Full`](https://python-all.ru/3.10/library/queue.html#queue.Full), если за это время место не освободилось. В противном случае (*block* ложен), помещает элемент в очередь, если место свободно немедленно, иначе возбуждает исключение [`Full`](https://python-all.ru/3.10/library/queue.html#queue.Full) (в этом случае *timeout* игнорируется).8283#### `Queue.put_nowait(item)`8485Эквивалентно `put(item, block=False)`.8687#### `Queue.get(block=True, timeout=None)`8889Удаляет элемент из очереди и возвращает его. Если необязательный аргумент *block* равен true, а *timeout* равен `None` (по умолчанию), при необходимости блокирует выполнение, пока элемент не станет доступен. Если *timeout* – положительное число, блокирует выполнение не более чем на *timeout* секунд и вызывает исключение [`Empty`](https://python-all.ru/3.10/library/queue.html#queue.Empty), если за это время элемент не появился. В противном случае (*block* равен false) возвращает элемент, если он доступен немедленно, иначе вызывает исключение [`Empty`](https://python-all.ru/3.10/library/queue.html#queue.Empty) (*timeout* в этом случае игнорируется).9091До версии 3.0 в системах POSIX и во всех версиях Windows, если *block* истинен и *timeout* равен `None`, эта операция переходит в непрерываемое ожидание на базовой блокировке. Это означает, что никакие исключения не могут возникнуть, и, в частности, SIGINT не вызовет [`KeyboardInterrupt`](https://python-all.ru/3.10/library/exceptions.html#KeyboardInterrupt).9293#### `Queue.get_nowait()`9495Эквивалентно `get(False)`.9697Предлагаются два метода для отслеживания того, были ли задачи, поставленные в очередь, полностью обработаны потоками-потребителями-демонами.9899#### `Queue.task_done()`100101Указывает, что ранее поставленная в очередь задача завершена. Используется потоками-потребителями очереди. Для каждого вызова [`get()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.get), использованного для получения задачи, последующий вызов [`task_done()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.task_done) сообщает очереди, что обработка задачи завершена.102103Если [`join()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.join) в данный момент заблокирован, он возобновит работу, когда все элементы будут обработаны (то есть для каждого элемента, который был [`put()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.put) в очередь, был получен вызов [`task_done()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.task_done)).104105Возбуждает [`ValueError`](https://python-all.ru/3.10/library/exceptions.html#ValueError), если вызывается больше раз, чем было помещено элементов в очередь.106107#### `Queue.join()`108109Блокируется до тех пор, пока все элементы в очереди не будут получены и обработаны.110111Счётчик незавершённых задач увеличивается каждый раз, когда элемент добавляется в очередь. Счётчик уменьшается, когда поток-потребитель вызывает [`task_done()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.task_done), чтобы указать, что элемент был получен и вся работа с ним завершена. Когда счетчик незавершённых задач падает до нуля, [`join()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.join) разблокируется.112113Пример ожидания завершения поставленных в очередь задач:114115```python116import threading117import queue118119q = queue.Queue()120121def worker():122    while True:123        item = q.get()124        print(f'Working on {item}')125        print(f'Finished {item}')126        q.task_done()127128# Запустить рабочий поток.129threading.Thread(target=worker, daemon=True).start()130131# Отправить рабочему тридцать запросов задач.132for item in range(30):133    q.put(item)134135# Ожидать завершения всех задач.136q.join()137print('All work completed')138```139140## Объекты SimpleQueue141142Объекты [`SimpleQueue`](https://python-all.ru/3.10/library/queue.html#queue.SimpleQueue) предоставляют описанные ниже публичные методы.143144#### `SimpleQueue.qsize()`145146Возвращает приблизительный размер очереди. Обратите внимание, qsize() \> 0 не гарантирует, что последующий вызов get() не заблокируется.147148#### `SimpleQueue.empty()`149150Возвращает `True`, если очередь пуста, и `False` в противном случае. Если empty() возвращает `False`, это не гарантирует, что последующий вызов get() не заблокируется.151152#### `SimpleQueue.put(item, block=True, timeout=None)`153154Помещает *элемент* в очередь. Метод никогда не блокируется и всегда выполняется успешно (за исключением возможных низкоуровневых ошибок, например, сбоя выделения памяти). Необязательные аргументы *block* и *timeout* игнорируются и предоставлены только для совместимости с [`Queue.put()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.put).155156**Особенность реализации CPython:** Этот метод имеет реализацию на C, которая является реентерабельной. То есть вызов `put()` или `get()` может быть прерван другим вызовом `put()` в том же потоке без взаимоблокировки или повреждения внутреннего состояния очереди. Это делает его подходящим для использования в деструкторах, таких как методы `__del__` или колбэки [`weakref`](https://python-all.ru/3.10/library/weakref.html#module-weakref).157158#### `SimpleQueue.put_nowait(item)`159160Эквивалентно `put(item, block=False)`, предусмотрено для совместимости с [`Queue.put_nowait()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.put_nowait).161162#### `SimpleQueue.get(block=True, timeout=None)`163164Удаляет элемент из очереди и возвращает его. Если необязательный аргумент *block* равен true, а *timeout* равен `None` (по умолчанию), при необходимости блокирует выполнение, пока элемент не станет доступен. Если *timeout* – положительное число, блокирует выполнение не более чем на *timeout* секунд и вызывает исключение [`Empty`](https://python-all.ru/3.10/library/queue.html#queue.Empty), если за это время элемент не появился. В противном случае (*block* равен false) возвращает элемент, если он доступен немедленно, иначе вызывает исключение [`Empty`](https://python-all.ru/3.10/library/queue.html#queue.Empty) (*timeout* в этом случае игнорируется).165166#### `SimpleQueue.get_nowait()`167168Эквивалентно `get(False)`.169170> **См. также**171>172> **Класс [`multiprocessing.Queue`](https://python-all.ru/3.10/library/multiprocessing.html#multiprocessing.Queue)**173>174> Класс очереди для использования в контексте многопроцессорной обработки (а не многопоточности).175>176> [`collections.deque`](https://python-all.ru/3.10/library/collections.html#collections.deque) – это альтернативная реализация неограниченных очередей с быстрыми атомарными операциями [`append()`](https://python-all.ru/3.10/library/collections.html#collections.deque.append) и [`popleft()`](https://python-all.ru/3.10/library/collections.html#collections.deque.popleft), которые не требуют блокировок и также поддерживают индексирование.177