17.7. queue — 同步队列类 ¶

源代码： Lib/queue.py

---

The queue 模块实现多生产者、多消费者队列。在线程化编程中尤其有用，当必须在多个线程之间安全交换信息时。 Queue class in this module implements all the required locking semantics. It depends on the availability of thread support in Python; see the threading 模块。

The module implements three types of queue, which differ only in the order in which the entries are retrieved. In a FIFO queue, the first tasks added are the first retrieved. In a LIFO queue, the most recently added entry is the first retrieved (operating like a stack). With a priority queue, the entries are kept sorted (using the heapq 模块) 且首先检索最低值条目。

Internally, the module uses locks to temporarily block competing threads; however, it is not designed to handle reentrancy within a thread.

The queue 模块定义下列类和异常：

class 队列。 队列 ( 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 <= 0，队列大小无限。

class 队列。 LifoQueue ( maxsize=0 ) ¶

Constructor for a LIFO 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 <= 0，队列大小无限。

class 队列。 PriorityQueue ( maxsize=0 ) ¶

优先级队列构造函数。 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 <= 0，队列大小无限。

The lowest valued entries are retrieved first (the lowest valued entry is the one returned by sorted(list(entries))[0] ). A typical pattern for entries is a tuple in the form: (priority_number, data) .

exception 队列。 Empty ¶

异常被引发当非阻塞 get() (或 get_nowait() ) 被调用当 Queue 对象为空。

exception 队列。 Full ¶

异常被引发当非阻塞 put() (或 put_nowait() ) 被调用当 Queue 对象已满。

17.7.1. 队列对象 ¶

Queue 对象 ( Queue , LifoQueue ，或 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 ) ¶

Put item 进队列。若可选自变量 block 为 True 和 timeout is None (默认)，阻塞若有必要直到空闲槽可用。若 timeout 是正数，它阻塞最多 timeout 秒并引发 Full 异常若在该时间内无可用空闲槽。否则 ( block 为 False)，将项放入队列若空闲槽立即可用，否则引发 Full 异常 ( timeout 被忽略在这种情况下)。

Queue. put_nowait ( item ) ¶

相当于 put(item, False) .

Queue. get ( block=True , timeout=None ) ¶

移除并返回项从队列。若可选自变量 block 为 True 和 timeout is None (默认)，阻塞若有必要直到项可用。若 timeout 是正数，它阻塞最多 timeout 秒并引发 Empty 异常若在该时间内无可用项。否则 ( block 为 False)，返回项若立即可用，否则引发 Empty 异常 ( timeout 被忽略在这种情况下)。

Queue. get_nowait ( ) ¶

相当于 get(False) .

提供 2 方法以支持追踪排队任务是否已被守护消费者线程完全处理。

Queue. task_done ( ) ¶

指示先前排队任务已完成。用于队列消费者线程。对于每个 get() 用于抓取任务，后续调用 task_done() tells the queue that the processing on the task is complete.

若 join() is currently blocking, it will resume when all items have been processed (meaning that a task_done() call was received for every item that had been put() into the queue).

引发 ValueError if called more times than there were items placed in the queue.

Queue. join ( ) ¶

阻塞，直到获取并处理队列中的所有项为止。

The count of unfinished tasks goes up whenever an item is added to the queue. The count goes down whenever a consumer thread calls task_done() to indicate that the item was retrieved and all work on it is complete. When the count of unfinished tasks drops to zero, join() unblocks.

如何等待排队任务完成的范例：

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()
					

另请参阅

类 multiprocessing.Queue

A queue class for use in a multi-processing (rather than multi-threading) context.

collections.deque is an alternative implementation of unbounded queues with fast atomic append() and popleft() operations that do not require locking.

内容表

• 17.7. queue — 同步队列类
  • 17.7.1. 队列对象

上一话题

17.6. sched — 事件调度器

下一话题

17.8. dummy_threading — 直接置换 threading 模块

本页

• 报告 Bug
• 展示源