`queue.md`

257 строк · 12.0 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.1/library/queue.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 8.8. `очередь` – Синхронизированный класс очереди89Модуль `очередь` реализует очереди с множеством производителей и потребителей. Особенно полезен в многопоточном программировании, когда необходимо безопасно обмениваться данными между несколькими потоками. Класс [`Queue`](https://python-all.ru/3.1/library/queue.html#queue.Queue) в этом модуле реализует всю необходимую семантику блокировок. Он зависит от наличия поддержки потоков в Python; см. модуль [`threading`](https://python-all.ru/3.1/library/threading.html#module-threading).1011Реализует три типа очередей, различающихся только порядком извлечения элементов. В очереди FIFO первыми добавляются первые задачи, они же извлекаются первыми. В очереди LIFO последний добавленный элемент извлекается первым (работает как стек). В очереди с приоритетом элементы хранятся отсортированными (с использованием модуля [`heapq`](https://python-all.ru/3.1/library/heapq.html#module-heapq)) и извлекается элемент с наименьшим значением.1213Модуль `очередь` определяет следующие классы и исключения:1415#### `class queue.Queue(maxsize)`1617Конструктор очереди FIFO.1819*maxsize*2021– целое число, которое задает верхнюю границу количества элементов, которые можно поместить в очередь. Вставка будет блокироваться, как только этот размер достигнут, пока элементы очереди не будут потреблены. Если2223*maxsize*2425меньше или равно нулю, размер очереди бесконечен.2627#### `class queue.LifoQueue(maxsize)`2829Конструктор очереди LIFO.3031*maxsize*3233– целое число, которое задает верхнюю границу количества элементов, которые можно поместить в очередь. Вставка будет блокироваться, как только этот размер достигнут, пока элементы очереди не будут потреблены. Если3435*maxsize*3637меньше или равно нулю, размер очереди бесконечен.3839#### `class queue.PriorityQueue(maxsize)`4041Конструктор для очереди с приоритетом. *maxsize* – целое число, задающее верхний предел количества элементов, которые можно поместить в очередь. Вставка будет блокироваться, когда этот размер достигнут, пока элементы очереди не будут потреблены. Если *maxsize* меньше или равно нулю, размер очереди бесконечен.4243Элементы с наименьшим значением извлекаются первыми (элемент с наименьшим значением – это то, что возвращает `sorted(list(entries))[0]`). Типичный шаблон для элементов – кортеж вида: `(priority_number, data)`.4445#### `exception queue.Empty`4647Исключение возникает при вызове неблокирующего4849`get()`5051(или5253`get_nowait()`5455) для пустого объекта5657[`очереди`](https://python-all.ru/3.1/library/queue.html#queue.Queue)5859.6061#### `exception queue.Full`6263Исключение возникает при вызове неблокирующего6465`put()`6667(или6869`put_nowait()`7071) для полного объекта7273[`очереди`](https://python-all.ru/3.1/library/queue.html#queue.Queue)7475.7677> **См. также**78>79> [`collections.deque`](https://python-all.ru/3.1/library/collections.html#collections.deque) – альтернативная реализация неограниченных очередей с быстрыми атомарными операциями `append()` и `popleft()`, не требующими блокировки.8081## 8.8.1. Объекты очереди8283Объекты очереди ([`Queue`](https://python-all.ru/3.1/library/queue.html#queue.Queue), [`LifoQueue`](https://python-all.ru/3.1/library/queue.html#queue.LifoQueue) или [`PriorityQueue`](https://python-all.ru/3.1/library/queue.html#queue.PriorityQueue)) предоставляют описанные ниже публичные методы.8485#### `Queue.qsize()`8687Возвращает приблизительный размер очереди. Обратите внимание: qsize() \> 0 не гарантирует, что последующий вызов get() не заблокируется, равно как qsize() \< maxsize не гарантирует, что put() не заблокируется.8889#### `Queue.empty()`9091Возвращает9293`True`9495, если очередь пуста, и9697`False`9899в противном случае. Если empty() возвращает100101`True`102103, это не гарантирует, что последующий вызов put() не будет блокироваться. Аналогично, если empty() возвращает104105`False`106107, это не гарантирует, что последующий вызов get() не будет блокироваться.108109#### `Queue.full()`110111Возвращает112113`True`114115, если очередь полна, и116117`False`118119в противном случае. Если full() возвращает120121`True`122123, это не гарантирует, что последующий вызов get() не будет блокироваться. Аналогично, если full() возвращает124125`False`126127, это не гарантирует, что последующий вызов put() не будет блокироваться.128129#### `Queue.put(item[, block[, timeout]])`130131Помещает132133*item*134135в очередь. Если необязательный аргумент136137*block*138139равен true, а140141*timeout*142143равен None (значение по умолчанию), при необходимости блокируется до появления свободного места. Если144145*timeout*146147– положительное число, блокируется не более чем на148149*timeout*150151секунд и возбуждает исключение152153[`Full`](https://python-all.ru/3.1/library/queue.html#queue.Full)154155, если свободное место не появилось за это время. В противном случае (156157*block*158159равен false) помещает элемент в очередь, если свободное место есть немедленно; иначе возбуждает исключение160161[`Full`](https://python-all.ru/3.1/library/queue.html#queue.Full)162163(в этом случае164165*timeout*166167игнорируется).168169#### `Queue.put_nowait(item)`170171Эквивалентно172173`put(item, False)`174175.176177#### `Queue.get([block[, timeout]])`178179Удаляет и возвращает элемент из очереди. Если необязательный аргумент180181*block*182183равен true и184185*timeout*186187равен None (по умолчанию), при необходимости блокируется до появления элемента. Если188189*timeout*190191– положительное число, он блокируется не более чем на192193*timeout*194195секунд и возбуждает исключение196197[`Empty`](https://python-all.ru/3.1/library/queue.html#queue.Empty)198199, если за это время элемент не появился. В противном случае (200201*block*202203равен false) возвращает элемент, если он доступен немедленно; иначе возбуждает исключение204205[`Empty`](https://python-all.ru/3.1/library/queue.html#queue.Empty)206207(в этом случае208209*timeout*210211игнорируется).212213#### `Queue.get_nowait()`214215Эквивалентно216217`get(False)`218219.220221Предлагаются два метода для отслеживания того, были ли задачи, поставленные в очередь, полностью обработаны потоками-потребителями-демонами.222223#### `Queue.task_done()`224225Указывает, что ранее поставленная задача выполнена. Используется потоками-потребителями очереди. Для каждого [`get()`](https://python-all.ru/3.1/library/queue.html#queue.Queue.get), используемого для получения задачи, последующий вызов [`task_done()`](https://python-all.ru/3.1/library/queue.html#queue.Queue.task_done) сообщает очереди, что обработка задачи завершена.226227Если [`join()`](https://python-all.ru/3.1/library/queue.html#queue.Queue.join) в данный момент блокируется, он возобновит работу, когда все элементы будут обработаны (то есть вызов [`task_done()`](https://python-all.ru/3.1/library/queue.html#queue.Queue.task_done) был получен для каждого элемента, который был помещён в очередь с помощью [`put()`](https://python-all.ru/3.1/library/queue.html#queue.Queue.put)).228229Возбуждает [`ValueError`](https://python-all.ru/3.1/library/exceptions.html#ValueError), если вызывается больше раз, чем было помещено элементов в очередь.230231#### `Queue.join()`232233Блокируется до тех пор, пока все элементы в очереди не будут получены и обработаны.234235Счётчик незавершённых задач увеличивается каждый раз, когда элемент добавляется в очередь. Счётчик уменьшается каждый раз, когда поток-потребитель вызывает [`task_done()`](https://python-all.ru/3.1/library/queue.html#queue.Queue.task_done), чтобы указать, что элемент извлечён и вся работа над ним завершена. Когда счётчик незавершённых задач падает до нуля, [`join()`](https://python-all.ru/3.1/library/queue.html#queue.Queue.join) разблокируется.236237Пример ожидания завершения поставленных в очередь задач:238239```python240def worker():241    while True:242        item = q.get()243        do_work(item)244        q.task_done()245246q = Queue()247for i in range(num_worker_threads):248     t = Thread(target=worker)249     t.daemon = True250     t.start()251252for item in source():253    q.put(item)254255q.join()       # ожидать завершения всех задач256```257