"""有界队列：背压、逐项确认、失败记录和排空关闭。Python >=3.13。"""
import asyncio
import time


async def main():
    queue = asyncio.Queue(maxsize=2)
    gate = asyncio.Event()
    admitted = []
    completed = []
    failures = []
    waits = []
    peak = 0

    async def worker():
        await gate.wait()  # 教学控制点：先让队列满，确定观察阻塞。
        while True:
            item = await queue.get()
            try:
                if item is None:
                    return
                await asyncio.sleep(0.01)
                if item == 3:
                    raise ValueError("bad job")
                completed.append(item)
            except ValueError as error:
                failures.append((item, str(error)))
            finally:
                queue.task_done()  # 成功、失败、终止标记都确认一次。

    async def producer():
        nonlocal peak
        for item in range(6):
            start = time.monotonic()
            await queue.put(item)  # 无界 create_task 会绕过这项背压。
            waits.append(time.monotonic() - start)
            admitted.append(item)
            peak = max(peak, queue.qsize())

    async with asyncio.TaskGroup() as group:
        group.create_task(worker())
        producer_task = group.create_task(producer())
        # 等待队列达到确定状态，不用固定 sleep 推断调度先后。
        async with asyncio.timeout(2):
            while queue.qsize() != 2:
                await asyncio.sleep(0)
            await asyncio.sleep(0)
            assert not producer_task.done()
            assert admitted == [0, 1]
            print("backpressure: queue=2 producer pending")
            gate.set()
            await producer_task  # 停止准入：生产者结束后再排空。
            await queue.join()
            await queue.put(None)
    assert peak <= 2
    assert sorted(completed) == [0, 1, 2, 4, 5]
    assert failures == [(3, "bad job")]
    assert queue.empty()
    print("completed:", completed, "failures:", failures)
    print("peak:", peak, "put waits:", waits)  # 时长随机器变化，不作性能结论。


if __name__ == "__main__":
    asyncio.run(main())
