queue — 一個同步的隊列類 · Python3.7.3官方文檔簡體中文

### 導航 - [索引](../genindex.xhtml "總目錄") - [模塊](../py-modindex.xhtml "Python 模塊索引") | - [下一頁](_thread.xhtml "_thread --- 底層多線程 API") | - [上一頁](sched.xhtml "sched --- 事件調度器") | - ![](https://box.kancloud.cn/a721fc7ec672275e257bbbfde49a4d4e_16x16.png) - [Python](https://www.python.org/) ? - zh\_CN 3.7.3 [文檔](../index.xhtml) ? - [Python 標準庫](index.xhtml) ? - [并發執行](concurrency.xhtml) ? - $('.inline-search').show(0); | # [`queue`](#module-queue "queue: A synchronized queue class.") --- 一個同步的隊列類 **源代碼:** [Lib/queue.py](https://github.com/python/cpython/tree/3.7/Lib/queue.py) \[https://github.com/python/cpython/tree/3.7/Lib/queue.py\] - - - - - - [`queue`](#module-queue "queue: A synchronized queue class.") 模塊實現多生產者，多消費者隊列。當信息必須安全的在多線程之間交換時，它在線程編程中是特別有用的。此模塊中的 [`Queue`](#queue.Queue "queue.Queue") 類實現了所有鎖定需求的語義。它依賴于Python支持的線程可用性；請參閱 [`threading`](threading.xhtml#module-threading "threading: Thread-based parallelism.") 模塊。模塊實現了三種類型的隊列，它們的區別僅僅是條目取回的順序。在 FIFO 隊列中，先添加的任務先取回。在 LIFO 隊列中，最近被添加的條目先取回(操作類似一個堆棧)。優先級隊列中，條目將保持排序( 使用 [`heapq`](heapq.xhtml#module-heapq "heapq: Heap queue algorithm (a.k.a. priority queue).") 模塊 ) 并且最小值的條目第一個返回。在內部，這三個類型的隊列使用鎖來臨時阻塞競爭線程；然而，它們并未被設計用于線程的重入性處理。此外，模塊實現了一個 "簡單的" FIFO 隊列類型， [`SimpleQueue`](#queue.SimpleQueue "queue.SimpleQueue") ，這個特殊實現為小功能在交換中提供額外的保障。 [`queue`](#module-queue "queue: A synchronized queue class.") 模塊定義了下列類和異常： *class* `queue.``Queue`(*maxsize=0*)Constructor for a FIFO queue. *maxsize* is an integer that sets the upperbound limit on the number of items that can be placed in the queue. Insertion will block once this size has been reached, until queue items are consumed. If *maxsize* is less than or equal to zero, the queue size is infinite. *class* `queue.``LifoQueue`(*maxsize=0*)LIFO 隊列構造函數。 *maxsize* 是個整數，用于設置可以放入隊列中的項目數的上限。當達到這個大小的時候，插入操作將阻塞至隊列中的項目被消費掉。如果 *maxsize* 小于等于零，隊列尺寸為無限大。 *class* `queue.``PriorityQueue`(*maxsize=0*)優先級隊列構造函數。 *maxsize* 是個整數，用于設置可以放入隊列中的項目數的上限。當達到這個大小的時候，插入操作將阻塞至隊列中的項目被消費掉。如果 *maxsize* 小于等于零，隊列尺寸為無限大。最小值先被取出( 最小值條目是由 `sorted(list(entries))[0]` 返回的條目)。條目的典型模式是一個以下形式的元組： `(priority_number, data)` 。如果 *data* 元素沒有可比性，數據將被包裝在一個類中，忽略數據值，僅僅比較優先級數字： ``` from dataclasses import dataclass, field from typing import Any @dataclass(order=True) class PrioritizedItem: priority: int item: Any=field(compare=False) ``` *class* `queue.``SimpleQueue`無界的 FIFO 隊列構造函數。簡單的隊列，缺少任務跟蹤等高級功能。 3\.7 新版功能. *exception* `queue.``Empty`對空的 [`Queue`](#queue.Queue "queue.Queue") 對象，調用非阻塞的 [`get()`](#queue.Queue.get "queue.Queue.get") (or [`get_nowait()`](#queue.Queue.get_nowait "queue.Queue.get_nowait")) 時，引發的異常。 *exception* `queue.``Full`對滿的 [`Queue`](#queue.Queue "queue.Queue") 對象，調用非阻塞的 [`put()`](#queue.Queue.put "queue.Queue.put") (or [`put_nowait()`](#queue.Queue.put_nowait "queue.Queue.put_nowait")) 時，引發的異常。 ## Queue對象隊列對象 ([`Queue`](#queue.Queue "queue.Queue"), [`LifoQueue`](#queue.LifoQueue "queue.LifoQueue"), 或者 [`PriorityQueue`](#queue.PriorityQueue "queue.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* 是 true 并且 *timeout* 是 `None` (默認)，則在必要時阻塞至有空閑插槽可用。如果 *timeout* 是個正數，將最多阻塞 *timeout* 秒，如果在這段時間沒有可用的空閑插槽，將引發 [`Full`](#queue.Full "queue.Full") 異常。反之 (*block* 是 false)，如果空閑插槽立即可用，則把 *item* 放入隊列，否則引發 [`Full`](#queue.Full "queue.Full") 異常 ( 在這種情況下，*timeout* 將被忽略)。 `Queue.``put_nowait`(*item*)相當于 `put(item, False)` 。 `Queue.``get`(*block=True*, *timeout=None*)從隊列中移除并返回一個項目。如果可選參數 *block* 是 true 并且 *timeout* 是 `None` (默認值)，則在必要時阻塞至項目可得到。如果 *timeout* 是個正數，將最多阻塞 *timeout* 秒，如果在這段時間內項目不能得到，將引發 [`Empty`](#queue.Empty "queue.Empty") 異常。反之 (*block* 是 false) , 如果一個項目立即可得到，則返回一個項目，否則引發 [`Empty`](#queue.Empty "queue.Empty") 異常 (這種情況下，*timeout* 將被忽略)。 POSIX系統3.0之前，以及所有版本的Windows系統中，如果 *block* 是 true 并且 *timeout* 是 `None` ，這個操作將進入基礎鎖的不間斷等待。這意味著，沒有異常能發生，尤其是 SIGINT 將不會觸發 [`KeyboardInterrupt`](exceptions.xhtml#KeyboardInterrupt "KeyboardInterrupt") 異常。 `Queue.``get_nowait`()相當于 `get(False)` 。提供了兩個方法，用于支持跟蹤排隊的任務是否被守護的消費者線程完整的處理。 `Queue.``task_done`()表示前面排隊的任務已經被完成。被隊列的消費者線程使用。每個 [`get()`](#queue.Queue.get "queue.Queue.get") 被用于獲取一個任務，后續調用 [`task_done()`](#queue.Queue.task_done "queue.Queue.task_done") 告訴隊列，該任務的處理已經完成。如果 [`join()`](#queue.Queue.join "queue.Queue.join") 當前正在阻塞，在所有條目都被處理后，將解除阻塞(意味著每個 [`put()`](#queue.Queue.put "queue.Queue.put") 進隊列的條目的 [`task_done()`](#queue.Queue.task_done "queue.Queue.task_done") 都被收到)。如果被調用的次數多于放入隊列中的項目數量，將引發 [`ValueError`](exceptions.xhtml#ValueError "ValueError") 異常。 `Queue.``join`()阻塞至隊列中所有的元素都被接收和處理完畢。當條目添加到隊列的時候，未完成任務的計數就會增加。每當消費者線程調用 [`task_done()`](#queue.Queue.task_done "queue.Queue.task_done") 表示這個條目已經被回收，該條目所有工作已經完成，未完成計數就會減少。當未完成計數降到零的時候， [`join()`](#queue.Queue.join "queue.Queue.join") 阻塞被解除。如何等待排隊的任務被完成的示例： ``` def worker(): while True: item = q.get() if item is None: break do_work(item) q.task_done() q = queue.Queue() threads = [] for i in range(num_worker_threads): t = threading.Thread(target=worker) t.start() threads.append(t) for item in source(): q.put(item) # block until all tasks are done q.join() # stop workers for i in range(num_worker_threads): q.put(None) for t in threads: t.join() ``` ## SimpleQueue 對象 [`SimpleQueue`](#queue.SimpleQueue "queue.SimpleQueue") 對象提供下列描述的公共方法。 `SimpleQueue.``qsize`()返回隊列的大致大小。注意，qsize() > 0 不保證后續的 get() 不被阻塞。 `SimpleQueue.``empty`()如果隊列為空，返回 `True` ，否則返回 `False` 。如果 empty() 返回 `False` ，不保證后續調用的 get() 不被阻塞。 `SimpleQueue.``put`(*item*, *block=True*, *timeout=None*)將 *item* 放入隊列。此方法永不阻塞，始終成功（除了潛在的低級錯誤，例如內存分配失敗）。可選參數 *block* 和 *timeout* 僅僅是為了保持 [`Queue.put()`](#queue.Queue.put "queue.Queue.put") 的兼容性而提供，其值被忽略。 **CPython implementation detail:** This method has a C implementation which is reentrant. That is, a `put()` or `get()` call can be interrupted by another `put()`call in the same thread without deadlocking or corrupting internal state inside the queue. This makes it appropriate for use in destructors such as `__del__` methods or [`weakref`](weakref.xhtml#module-weakref "weakref: Support for weak references and weak dictionaries.") callbacks. `SimpleQueue.``put_nowait`(*item*)相當于 `put(item)` ，僅為保持 [`Queue.put_nowait()`](#queue.Queue.put_nowait "queue.Queue.put_nowait") 兼容性而提供。 `SimpleQueue.``get`(*block=True*, *timeout=None*)從隊列中移除并返回一個項目。如果可選參數 *block* 是 true 并且 *timeout* 是 `None` (默認值)，則在必要時阻塞至項目可得到。如果 *timeout* 是個正數，將最多阻塞 *timeout* 秒，如果在這段時間內項目不能得到，將引發 [`Empty`](#queue.Empty "queue.Empty") 異常。反之 (*block* 是 false) , 如果一個項目立即可得到，則返回一個項目，否則引發 [`Empty`](#queue.Empty "queue.Empty") 異常 (這種情況下，*timeout* 將被忽略)。 `SimpleQueue.``get_nowait`()相當于 `get(False)` 。參見類 [`multiprocessing.Queue`](multiprocessing.xhtml#multiprocessing.Queue "multiprocessing.Queue")一個用于多進程上下文的隊列類（而不是多進程） [`collections.deque`](collections.xhtml#collections.deque "collections.deque") 是無界隊列的替代實現，具有快速原子的 [`append()`](collections.xhtml#collections.deque.append "collections.deque.append") 和 [`popleft()`](collections.xhtml#collections.deque.popleft "collections.deque.popleft") 操作，不需要鎖定。 ### 導航 - [索引](../genindex.xhtml "總目錄") - [模塊](../py-modindex.xhtml "Python 模塊索引") | - [下一頁](_thread.xhtml "_thread --- 底層多線程 API") | - [上一頁](sched.xhtml "sched --- 事件調度器") | - ![](https://box.kancloud.cn/a721fc7ec672275e257bbbfde49a4d4e_16x16.png) - [Python](https://www.python.org/) ? - zh\_CN 3.7.3 [文檔](../index.xhtml) ? - [Python 標準庫](index.xhtml) ? - [并發執行](concurrency.xhtml) ? - $('.inline-search').show(0); | ? [版權所有](../copyright.xhtml) 2001-2019, Python Software Foundation. Python 軟件基金會是一個非盈利組織。 [請捐助。](https://www.python.org/psf/donations/) 最后更新于 5月 21, 2019. [發現了問題](../bugs.xhtml)？使用[Sphinx](http://sphinx.pocoo.org/)1.8.4 創建。