Queue Types in Python

The Story That Explains All Queues 🚶सारी Queues समझाने वाली कहानी 🚶一个讲清所有队列的故事 🚶

The Big Picture — All Queue Types at a Glance 🗺️बड़ी तस्वीर — सारे Queue Types एक नज़र में 🗺️全局视角 — 一眼看懂所有队列类型 🗺️

🎮 Simulator: Queue Playground🎮 Simulator: Queue Playground🎮 模拟器：队列游乐场

Pick a queue type, add and remove items, and watch which item comes out. The code on the left grows with every click. The results were checked against Python on 400 random sequences — including the exact error messages.

एक queue type चुनिए, items जोड़िए और निकालिए, और देखिए कौन-सा item बाहर आता है। हर click के साथ बाईं ओर का code बढ़ता है। नतीजे 400 random sequences पर Python से जाँचे गए — सटीक error messages समेत।

选一种队列类型，添加和移除元素，看看哪个元素先出来。左边的代码会随着每次点击增长。结果已在 400 个随机序列上与 Python 核对 — 包括精确的错误信息。

Type 1 — FIFO Queue (First In, First Out) ☕Type 1 — FIFO Queue (पहले आया, पहले गया) ☕类型 1 — FIFO 队列（先进先出）☕

The default and most natural queue. Items join at the tail and leave from the head, in exactly the order they arrived — the coffee shop line.

सबसे आम और स्वाभाविक queue। Items tail पर जुड़ते हैं और head से निकलते हैं, ठीक उसी क्रम में जिसमें आए — कॉफ़ी की दुकान की कतार।

最常见、最自然的队列。元素从 队尾 进入，从 队头 离开，严格按照到达的顺序 — 就像咖啡店的队伍。

from collections import deque

# deque = the fast Python FIFO (O(1) at both ends)
q = deque()
q.append("A")          # enqueue at the tail
q.append("B")
q.append("C")

print(q.popleft())     # "A" - dequeue from the head
print(q.popleft())     # "B"
print(q.popleft())     # "C"

import timeit

for n in (1_000, 10_000, 100_000):
    t_list = timeit.timeit("while q: q.pop(0)",
                           setup=f"q = list(range({n}))", number=1)
    t_deque = timeit.timeit("while q: q.popleft()",
                            setup=f"from collections import deque; q = deque(range({n}))", number=1)
    print(f"{n:>7,} items: list.pop(0) {t_list*1000:8.2f} ms | "
          f"deque.popleft() {t_deque*1000:6.2f} ms | {t_list/t_deque:5.0f}x slower")

🏁 Simulator: pop(0) Race🏁 Simulator: pop(0) Race🏁 模拟器：pop(0) 赛跑

Watch why pop(0) is slow: after removing the first item, every other item must move one place left. popleft() just moves the start. The bars show real timings for emptying a whole queue (best of 3 runs on our test machine).

देखिए pop(0) धीमा क्यों है: पहला item हटाने के बाद हर दूसरे item को एक जगह बाईं ओर खिसकना पड़ता है। popleft() बस शुरुआत आगे बढ़ाता है। Bars पूरी queue ख़ाली करने की असली timings दिखाते हैं (हमारी test machine पर 3 runs में सबसे अच्छा)।

看看 pop(0) 为什么慢：移除第一个元素后，其余每个元素都要向左挪一位。popleft() 只是移动起点。条形图显示清空整个队列的真实耗时（在我们测试机上 3 次运行中的最好成绩）。

Type 2 — LIFO Queue (Stack) 🍽️Type 2 — LIFO Queue (Stack) 🍽️类型 2 — LIFO 队列（栈）🍽️

A stack. Items go in and come out at the same end — the top. The last thing you added is the first thing you get back. Perfect for undo history, function calls and depth-first search.

एक stack। Items एक ही सिरे — top — से अंदर जाते और बाहर आते हैं। जो आख़िर में डाला, वही सबसे पहले वापस मिलता है। Undo history, function calls और depth-first search के लिए बढ़िया।

这就是 栈。元素从同一端 — 顶部 — 进出。最后放进去的最先拿回来。非常适合撤销历史、函数调用和深度优先搜索。

# Option A: Python list as a stack (O(1) at the end)
stack = []
stack.append("A")          # push
stack.append("B")
stack.append("C")
print(stack.pop())         # "C" - last in, first out
print(stack.pop())         # "B"

# Option B: collections.deque (also O(1); append/pop are thread-safe)
from collections import deque
stack = deque()
stack.append("A")
stack.append("B")
print(stack.pop())         # "B"

# Option C: queue.LifoQueue (thread-safe, blocking API)
from queue import LifoQueue
s = LifoQueue()
s.put("A"); s.put("B"); s.put("C")
print(s.get())             # "C"

Type 3 — Priority Queue 🏥Type 3 — Priority Queue 🏥类型 3 — 优先队列 🏥

Items do not come out in the order they went in. Each item has a priority, and the most urgent one always comes out first. In Python "most urgent" means the smallest number, because Python's priority queues are min-heaps.

Items उस क्रम में बाहर नहीं आते जिसमें अंदर गए। हर item की एक priority होती है, और सबसे ज़रूरी हमेशा पहले निकलता है। Python में "सबसे ज़रूरी" का मतलब सबसे छोटी संख्या है, क्योंकि Python की priority queues min-heaps हैं।

元素 不会 按进入的顺序出来。每个元素都有一个优先级，最紧急的总是最先出来。在 Python 中，"最紧急"指的是 最小 的数字，因为 Python 的优先队列都是最小堆。

# Option A: heapq - the low-level, fast min-heap
import heapq
pq = []
heapq.heappush(pq, (5, "Change ink"))
heapq.heappush(pq, (1, "Heart attack"))
heapq.heappush(pq, (3, "Cough"))
heapq.heappush(pq, (1, "Stroke"))
heapq.heappush(pq, (2, "Broken arm"))

while pq:
    print(heapq.heappop(pq))

# Option B: queue.PriorityQueue - thread-safe, blocking API
from queue import PriorityQueue
pq = PriorityQueue()
pq.put((5, "low urgency"))
pq.put((1, "urgent!"))
print(pq.get())            # (1, 'urgent!')

Type 4 — Deque (Double-Ended Queue) ↔️Type 4 — Deque (दोनों सिरों वाली Queue) ↔️类型 4 — 双端队列 Deque ↔️

Pronounced "deck". You can add or remove at either end in O(1). A deque can act as a FIFO, a LIFO, or both at once. collections.deque is the most flexible queue in the standard library.

"डेक" बोला जाता है। आप किसी भी सिरे पर O(1) में जोड़ या निकाल सकते हैं। Deque FIFO, LIFO, या दोनों एक साथ बन सकता है। collections.deque standard library की सबसे लचीली queue है।

读作 "deck"。你可以在 任意一端 以 O(1) 的速度添加或移除元素。deque 既能当 FIFO，也能当 LIFO，或者同时兼任。collections.deque 是标准库里最灵活的队列。

from collections import deque

d = deque(["B", "C", "D"])

# Add to either end
d.appendleft("A")
d.append("E")
print(d)                   # deque(['A', 'B', 'C', 'D', 'E'])

# Remove from either end
print(d.popleft())         # "A"
print(d.pop())             # "E"
print(d)                   # deque(['B', 'C', 'D'])

# Bounded deque - drops from the OPPOSITE end when full
recent = deque(maxlen=3)
for i in range(6):
    recent.append(i)
print(recent)              # deque([3, 4, 5], maxlen=3)

# Rotate - a fast circular shift
d = deque([1, 2, 3, 4, 5])
d.rotate(2)
print(d)                   # deque([4, 5, 1, 2, 3])
d.rotate(-1)
print(d)                   # deque([5, 1, 2, 3, 4])

Type 5 — Circular Queue (Ring Buffer) 🔁Type 5 — Circular Queue (Ring Buffer) 🔁类型 5 — 循环队列（环形缓冲区）🔁

A fixed-size queue where the head and tail positions wrap around from the end of the storage back to the start. It never grows and never shrinks — perfect when memory must stay fixed: audio buffers, sensor readings, network packets.

एक तय size की queue जिसमें head और tail की जगहें storage के अंत से वापस शुरुआत पर घूम जाती हैं। यह न बढ़ती है, न घटती है — जब memory तय रखनी हो तब बढ़िया: audio buffers, sensor readings, network packets।

一个固定大小的队列，head 和 tail 的位置会从存储末尾 绕回 开头。它从不增长也从不缩小 — 非常适合内存必须固定的场景：音频缓冲、传感器读数、网络数据包。

Building a circular queue from scratchCircular queue शुरू से बनाना从零实现循环队列

class CircularQueue:
    def __init__(self, capacity):
        self.buf = [None] * capacity
        self.cap = capacity
        self.head = 0          # index to read from
        self.tail = 0          # index to write to
        self.size = 0

    def enqueue(self, item):
        if self.size == self.cap:
            raise OverflowError("Queue full")
        self.buf[self.tail] = item
        self.tail = (self.tail + 1) % self.cap     # wrap around!
        self.size += 1

    def dequeue(self):
        if self.size == 0:
            raise IndexError("Queue empty")
        item = self.buf[self.head]
        self.buf[self.head] = None
        self.head = (self.head + 1) % self.cap     # wrap around!
        self.size -= 1
        return item

    def __len__(self):
        return self.size

# Demo
cq = CircularQueue(4)
for ch in "ABCD":
    cq.enqueue(ch)
print(cq.dequeue(), cq.dequeue())    # A B
cq.enqueue("E"); cq.enqueue("F")     # tail wraps back to slot 0
print(cq.buf)                        # ['E', 'F', 'C', 'D']

🔁 Simulator: Ring Buffer🔁 Simulator: Ring Buffer🔁 模拟器：环形缓冲区

Enqueue and dequeue on a ring of 6 slots. Watch head and tail go round and wrap back to slot 0. Then switch to deque(maxlen=6): instead of an error when full, it quietly drops the oldest item. Both were checked against Python on 300 random sequences.

6 slots वाले घेरे पर enqueue और dequeue कीजिए। head और tail को घूमते और slot 0 पर लौटते देखिए। फिर deque(maxlen=6) पर जाइए: भरने पर error की जगह यह चुपचाप सबसे पुराना item हटा देता है। दोनों 300 random sequences पर Python से जाँचे गए।

在一个有 6 个槽位的环上入队和出队。观察 head 和 tail 如何转圈并绕回槽位 0。然后切换到 deque(maxlen=6)：满了时它不会报错，而是悄悄丢掉最旧的元素。两者都已在 300 个随机序列上与 Python 核对。

Shortcut — deque(maxlen=…) as a circular bufferछोटा रास्ता — deque(maxlen=…) circular buffer की तरह捷径 — 用 deque(maxlen=…) 作环形缓冲区

from collections import deque

# A ring of the last 5 sensor readings
ring = deque(maxlen=5)
for reading in [10, 11, 13, 12, 14, 15, 16]:
    ring.append(reading)     # old readings drop off the LEFT automatically

print(ring)                  # deque([13, 12, 14, 15, 16], maxlen=5)
print(sum(ring) / len(ring)) # rolling average

Python's queue Module — Thread-Safe Queues 🔒Python का queue Module — Thread-Safe Queues 🔒Python 的 queue 模块 — 线程安全队列 🔒

The types above are ideas. When several threads share a queue, use the queue module: its classes lock for you, and their put()/get() can wait (block) until there is space or an item.

ऊपर के types विचार हैं। जब कई threads एक queue बाँटें, तो queue module लीजिए: इसकी classes आपके लिए lock करती हैं, और इनके put()/get() जगह या item मिलने तक इंतज़ार (block) कर सकते हैं।

上面的类型只是概念。当多个 线程 共享一个队列时，请使用 queue 模块：它的类会替你加锁，put()/get() 还能 等待（阻塞）直到有空位或有元素。

from queue import Queue, LifoQueue, PriorityQueue, SimpleQueue

# 1. Standard FIFO Queue
q = Queue(maxsize=10)
q.put("A"); q.put("B"); q.put("C")
print(q.get())             # A

# 2. Stack (LIFO)
s = LifoQueue()
s.put("A"); s.put("B"); s.put("C")
print(s.get())             # C - last in, first out

# 3. Priority (lowest number wins)
p = PriorityQueue()
p.put((3, "low"))
p.put((1, "urgent"))
p.put((2, "med"))
print(p.get())             # (1, 'urgent')

# 4. SimpleQueue - no maxsize, no join(), fastest
sq = SimpleQueue()
sq.put("fast")
print(sq.get())            # fast

How much faster is SimpleQueue?SimpleQueue कितना तेज़ है?SimpleQueue 快多少？

import timeit

for name in ("Queue", "SimpleQueue"):
    t = timeit.timeit("for i in r: q.put(i)\nfor i in r: q.get()",
                      setup=f"import queue; r = range(100_000); q = queue.{name}()",
                      number=1)
    print(f"{name:12s} 100,000 put+get: {t*1000:6.1f} ms")

Multiprocessing Queues — Between Processes 📫Multiprocessing Queues — Processes के बीच 📫多进程队列 — 进程之间 📫

The queue module works only between threads (one shared memory). Separate processes have separate memory, so use multiprocessing.Queue or JoinableQueue: they pickle each object and send it through a pipe.

queue module सिर्फ़ threads के बीच चलता है (एक साझा memory)। अलग processes की memory अलग होती है, इसलिए multiprocessing.Queue या JoinableQueue लीजिए: ये हर object को pickle करके pipe से भेजते हैं।

queue 模块只能在 线程 之间使用（共享同一块内存）。不同的 进程 内存是分开的，所以要用 multiprocessing.Queue 或 JoinableQueue：它们会把每个对象 pickle 后通过管道发送。

from multiprocessing import Process, JoinableQueue

def worker(q):
    while True:
        item = q.get()
        if item is None:
            break
        print(f"got {item}", flush=True)
        q.task_done()              # only on JoinableQueue

if __name__ == "__main__":
    q = JoinableQueue()            # like Queue + task_done/join
    p = Process(target=worker, args=(q,))
    p.start()
    for i in range(5):
        q.put(f"task {i}")
    q.join()                       # wait for all task_done()
    q.put(None)                    # poison pill
    p.join()
    print("all done")

asyncio.Queue — For async/await Code ⚡asyncio.Queue — async/await Code के लिए ⚡asyncio.Queue — 用于 async/await 代码 ⚡

Inside asyncio code, use asyncio.Queue. It looks like queue.Queue, but put() and get() are coroutines you must await. It is not thread-safe — it is safe between tasks inside one event loop.

asyncio code में asyncio.Queue लीजिए। यह queue.Queue जैसा दिखता है, पर put() और get() coroutines हैं जिन्हें await करना होता है। यह thread-safe नहीं है — यह एक event loop के अंदर tasks के बीच सुरक्षित है।

在 asyncio 代码中，请使用 asyncio.Queue。它看起来像 queue.Queue，但 put() 和 get() 是必须 await 的协程。它 不是线程安全的 — 它只在同一个事件循环内的任务之间是安全的。

import asyncio

async def producer(q, name):
    for i in range(3):
        await asyncio.sleep(0.1)
        await q.put(f"{name}-{i}")

async def consumer(q, name):
    while True:
        item = await q.get()
        if item is None:
            break
        print(f"[{name}] got {item}")
        q.task_done()

async def main():
    q = asyncio.Queue(maxsize=10)
    prods = [asyncio.create_task(producer(q, f"P{i}")) for i in range(2)]
    cons = [asyncio.create_task(consumer(q, f"C{i}")) for i in range(3)]
    await asyncio.gather(*prods)
    await q.join()
    for _ in cons:
        await q.put(None)
    await asyncio.gather(*cons)

asyncio.run(main())

heapq — The Raw Priority-Queue Building Block 🌲heapq — Priority Queue की बुनियादी ईंट 🌲heapq — 优先队列的基础构件 🌲

heapq turns a normal list into a min-heap. PriorityQueue uses it inside, plus locking. With no locking, it is the fastest choice for single-threaded priority work.

heapq एक सामान्य list को min-heap बना देता है। PriorityQueue अंदर से इसी को इस्तेमाल करता है, साथ में locking। बिना locking के यह single-thread priority काम के लिए सबसे तेज़ विकल्प है।

heapq 把普通列表变成 最小堆。PriorityQueue 内部就是用它再加上锁。没有锁的开销，它是单线程优先级任务的最快选择。

import heapq

# A heap is just a plain list, treated with heap operations
h = []
for x in [3, 1, 4, 1, 5]:
    heapq.heappush(h, x)
print(heapq.heappop(h))        # 1 (smallest first)
print(heapq.heappop(h))        # 1
print(heapq.heappop(h))        # 3

# Turn an existing list into a heap in O(n)
data = [7, 3, 9, 1, 4, 2]
heapq.heapify(data)            # in place
print(data)                    # [1, 3, 2, 7, 4, 9]

# Top-K largest / smallest in O(n log k)
print(heapq.nlargest(3, data))     # [9, 7, 4]
print(heapq.nsmallest(3, data))    # [1, 2, 3]

🌲 Simulator: Heap Lab🌲 Simulator: Heap Lab🌲 模拟器：堆实验室

Push numbers and pop the smallest. Watch a new item bubble up past bigger parents, and after a pop watch the last item move to the top and sink down. The list on the right is exactly what Python's heapq stores — checked on 300 random sequences.

Numbers push कीजिए और सबसे छोटा pop कीजिए। नए item को बड़े parents से ऊपर उठते देखिए, और pop के बाद आख़िरी item को top पर आकर नीचे बैठते देखिए। दाईं ओर की list ठीक वही है जो Python का heapq रखता है — 300 random sequences पर जाँची गई।

压入数字、弹出最小值。观察新元素如何越过更大的父节点 向上冒；弹出后，观察最后一个元素如何移到顶部再 向下沉。右边的列表正是 Python 的 heapq 存储的内容 — 已在 300 个随机序列上核对。

Equal priorities — the TypeError trapबराबर priorities — TypeError का जाल优先级相同 — TypeError 陷阱

import heapq

pq = []
heapq.heappush(pq, (1, {"task": "first urgent"}))
try:
    heapq.heappush(pq, (1, {"task": "second urgent"}))   # same priority!
except TypeError as e:
    print("TypeError:", e)

import heapq, itertools

# Priority queue with a tie-breaker counter
counter = itertools.count()
pq = []
heapq.heappush(pq, (1, next(counter), {"task": "first urgent"}))
heapq.heappush(pq, (1, next(counter), {"task": "second urgent"}))
heapq.heappush(pq, (3, next(counter), {"task": "normal"}))

while pq:
    print(heapq.heappop(pq)[2]["task"])

Bounded vs Unbounded Queues — Backpressure 🚰सीमित बनाम असीमित Queues — Backpressure 🚰有界 vs 无界队列 — 背压 🚰

If producers add items faster than consumers remove them, an unbounded queue just keeps growing — until memory runs out. A bounded queue (Queue(maxsize=N)) makes put() wait when it is full. The producers slow down to the consumers' speed. This is called backpressure.

अगर producers items को consumers के निकालने से तेज़ डालें, तो असीमित queue बढ़ती ही जाती है — memory ख़त्म होने तक। सीमित queue (Queue(maxsize=N)) भरने पर put() को इंतज़ार कराती है। Producers consumers की गति पर धीमे हो जाते हैं। इसे backpressure कहते हैं।

如果生产者放入元素的速度比消费者取出的速度快，无界 队列就会一直增长 — 直到内存耗尽。有界 队列（Queue(maxsize=N)）满了时会让 put() 等待，生产者于是放慢到消费者的速度。这就叫 背压。

🚰 Simulator: Backpressure Lab🚰 Simulator: Backpressure Lab🚰 模拟器：背压实验室

Set how many items the producer adds per tick, how many the consumer removes, and the queue's maxsize. The blue line is the queue length over 30 ticks; red marks show ticks where the producer had to wait. The model was checked against a queue.Queue run with put_nowait() for all 36 settings.

तय कीजिए producer हर tick में कितने items डालता है, consumer कितने निकालता है, और queue का maxsize। नीली line 30 ticks में queue की लंबाई है; लाल निशान वे ticks हैं जहाँ producer को इंतज़ार करना पड़ा। Model को सभी 36 settings के लिए put_nowait() वाले queue.Queue run से जाँचा गया।

设置生产者每个时刻放入多少个元素、消费者取出多少个，以及队列的 maxsize。蓝线是 30 个时刻内的队列长度；红色标记表示生产者不得不等待的时刻。该模型已针对全部 36 种设置，与使用 put_nowait() 的 queue.Queue 运行结果核对。

Real-World Scenarios — Which Queue for What 🌍असली Scenarios — किस काम के लिए कौन-सी Queue 🌍真实场景 — 什么任务用什么队列 🌍

Practical Example — A Multi-Queue Task Scheduler 🗓️काम का Example — Multi-Queue Task Scheduler 🗓️实用示例 — 多队列任务调度器 🗓️

Three worker threads pull from three queues in strict priority order: emergency tasks first, then normal tasks, then background work.

तीन worker threads तीन queues से सख़्त priority क्रम में काम लेते हैं: पहले emergency tasks, फिर normal tasks, फिर background काम।

三个工作线程按严格的优先顺序从 三个队列 中取任务：先紧急任务，再普通任务，最后是后台任务。

from queue import Queue, Empty
import threading, time

emergency = Queue()
normal = Queue()
background = Queue()

def worker():
    while True:
        # Try each queue in priority order
        for name, q in [("emergency", emergency),
                        ("normal", normal),
                        ("bg", background)]:
            try:
                task = q.get_nowait()
            except Empty:              # only "this queue is empty"
                continue
            if task is None:
                return
            print(f"[{name}] processing {task}")
            time.sleep(0.1)
            break
        else:
            time.sleep(0.05)           # all empty, wait a bit

# Feed the tasks FIRST, then start the workers
for i in range(10): background.put(f"bg-{i}")
for i in range(5):  normal.put(f"task-{i}")
for i in range(2):  emergency.put(f"fire-{i}")

threads = [threading.Thread(target=worker) for _ in range(3)]
for t in threads: t.start()

time.sleep(2)
for _ in threads: emergency.put(None)   # one poison pill per worker
for t in threads: t.join()

Complete Comparison Table 📋पूरी तुलना Table 📋完整对比表 📋

* A single append() or pop() on a list is atomic in CPython, but a mix of steps from several threads (check, then pop) can still race.

* CPython में list पर एक अकेला append() या pop() atomic है, पर कई threads से कई क़दमों का मेल (पहले check, फिर pop) फिर भी टकरा सकता है।

* 在 CPython 中，对列表的单次 append() 或 pop() 是原子的，但多个线程的多步操作（先检查再弹出）仍可能产生竞争。

Which Queue Should I Use? 🧭कौन-सी Queue लूँ? 🧭我该用哪种队列？🧭

Answer three questions and the picker walks the decision for you — the interactive version of the original flowchart.

तीन सवालों के जवाब दीजिए और picker आपके लिए फ़ैसला कर देगा — मूल flowchart का interactive version।

回答三个问题，选择器会替你完成决策 — 这是原流程图的互动版。

Bug Doctor, Golden Rules and Quiz 🏆Bug Doctor, सुनहरे नियम और Quiz 🏆Bug 医生、黄金法则与小测验 🏆

🩺 Simulator: Bug Doctor🩺 Simulator: Bug Doctor🩺 模拟器：Bug 医生

Six real queue mistakes. Buggy code on the left, fixed code on the right, changed lines marked. Every output is from a real run.

Queues की छह असली ग़लतियाँ। बाईं ओर buggy code, दाईं ओर ठीक किया हुआ, बदली lines चिह्नित। हर output असली run से है।

六个真实的队列错误。左边是有 bug 的代码，右边是修正后的代码，改动的行已标出。每个输出都来自真实运行。

Quick Quiz — 8 Questionsछोटा Quiz — 8 सवाल小测验 — 8 道题