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

将 item 放入队列。如果可选参数 block 为 true 且 timeout 为 None（默认值），则在有空闲槽位可用之前阻塞（如有必要）。如果 timeout 为正数，则最多阻塞 timeout 秒，如果在该时间内没有可用的空闲槽位，则引发 Full 异常。否则（block 为 false），如果有空闲槽位立即可用，则将项放入队列，否则引发 Full 异常（在这种情况下会忽略 timeout）。

如果队列已关闭，则引发 ShutDown。

Queue.put_nowait(item)¶

等效于 put(item, block=False)。

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

从队列中移除并返回一个项。如果可选参数 block 为 true 且 timeout 为 None (默认值)，则在必要时阻塞，直到有项可用。如果 timeout 为正数，则最多阻塞 timeout 秒，如果在该时间内没有可用的项，则引发 Empty 异常。否则（block 为 false），如果立即有项可用，则返回该项，否则引发 Empty 异常（在这种情况下会忽略 timeout）。

在 POSIX 系统上的 3.0 之前的版本中，以及在 Windows 上的所有版本中，如果 block 为 true 且 timeout 为 None，则此操作会在底层锁上进入不可中断的等待。这意味着不会发生任何异常，特别是 SIGINT 不会触发 KeyboardInterrupt。

如果队列已关闭且为空，或者队列已立即关闭，则会引发 ShutDown。

Queue.get_nowait()¶

等同于 get(False)。

提供了两种方法来支持跟踪排队的任务是否已由守护进程消费者线程完全处理。

Queue.task_done()¶

指示先前排队的任务已完成。由队列消费者线程使用。对于每个用于获取任务的 get()，随后对 task_done() 的调用会告诉队列，该任务的处理已完成。

如果 join() 当前正在阻塞，则当所有项都已处理完毕时（意味着对放入队列的每个项都已收到 task_done() 调用时），它将恢复。

shutdown(immediate=True) 对队列中剩余的每个项调用 task_done()。

如果调用次数多于放入队列中的项数，则会引发 ValueError。

Queue.join()¶

阻塞，直到队列中的所有项都已被获取和处理。

每当向队列添加项时，未完成任务的计数就会增加。每当消费者线程调用 task_done() 以指示该项已被检索且其上的所有工作均已完成时，该计数就会减少。当未完成任务的计数降至零时，join() 将解除阻塞。

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

import threading
import queue

q = queue.Queue()

def worker():
    while True:
        item = q.get()
        print(f'Working on {item}')
        print(f'Finished {item}')
        q.task_done()

# Turn-on the worker thread.
threading.Thread(target=worker, daemon=True).start()

# Send thirty task requests to the worker.
for item in range(30):
    q.put(item)

# Block until all tasks are done.
q.join()
print('All work completed')

SimpleQueue 对象¶

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() 兼容而提供。

CPython 实现细节：此方法具有可重入的 C 实现。也就是说，put() 或 get() 调用可以被同一线程中的另一个 put() 调用中断，而不会发生死锁或损坏队列内部状态。这使其适用于析构函数（例如 __del__ 方法）或 weakref 回调。

SimpleQueue.put_nowait(item)¶

等同于 put(item, block=False)，为了与 Queue.put_nowait() 兼容而提供。

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

从队列中移除并返回一个项。如果可选参数 block 为 true 且 timeout 为 None (默认值)，则在必要时阻塞，直到有项可用。如果 timeout 为正数，则最多阻塞 timeout 秒，如果在该时间内没有可用的项，则引发 Empty 异常。否则（block 为 false），如果立即有项可用，则返回该项，否则引发 Empty 异常（在这种情况下会忽略 timeout）。

SimpleQueue.get_nowait()¶

等同于 get(False)。