[asvetlov]

When the queue is full, get_nowait() pops a waiting putter and wakes it, but the freed slot stays open until that putter resumes. A later put() (fast path) or put_nowait() can take it; the woken putter then finds the queue full and is re-appended to the end of _putters, so items are put out of order and a waiter can be starved.

This PR reserves the freed slot for the woken putter:

• get_nowait() increments _reserved when it wakes a putter; full() counts reserved slots (qsize() + _reserved >= maxsize).
• The woken putter releases its reservation right before put_nowait(); if it is cancelled after being woken it passes the reservation to the next putter.
• shutdown() clears the counter.

This is the same idea asyncio.Semaphore uses for fairness (taking the value on the waiter's behalf). Compared to the earlier attempt (gh-112501):

• no new exceptions; full() is False still guarantees put_nowait() succeeds;
• O(1), no scanning of done futures;
• unreserved free slots remain usable, so Serhiy's example (two get_nowait() with one waiting putter, then put_nowait()) succeeds.

Behaviour change: full() may be True while qsize() < maxsize, for as long as a woken putter has not resumed. Documented in full()/put().

Getters are left as is: the issue is about the order items enter the queue, and reserving items would change the meaning of empty().

• Issue: asyncio.Queue: putting items out of order when it is full #83055

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #35522303 | 📁 Comparing 268b387 against main (6632294)

  🔍 Preview build  

2 files changed

± library/asyncio-queue.html
± whatsnew/changelog.html

[asvetlov]

@YvesDup here is my try to make asyncio.Queue fair.

[YvesDup]

@YvesDup here is my try to make asyncio.Queue fair.

Thank's a lot @asvetlov, I will have a look at begining of the next week.

[YvesDup]

@YvesDup here is my try to make asyncio.Queue fair.

That looks good. I'm starting to review the code
I closed my incomplete draft PR #160983 in favor of yours.

[YvesDup]

self.put_nowait returns only None. return statement could be removed.

[asvetlov]

Correct, but this line is not affected by the PR. I prefer to keep it untouched here

[OsmnvAslan]

Thanks for working on this! I tested it on a checkout merged with current main: test_queues passes, and the new tests fail on main as expected. I also ran a randomized put/get/cancel script (300 seeds) and a few edge cases (a woken putter that gets cancelled or closed via GeneratorExit, shutdown() and shutdown(immediate=True) with reserved slots). _reserved stayed consistent in all of them.

One compatibility concern: subclasses that override put() but inherit get_nowait(), or the other way round, and use _putters/_wakeup_next() directly. It's private API, but the pattern is fairly common: a GitHub code search for _wakeup_next(self._putters) outside queues.py gives more than 100 hits. For example, NVIDIA NeMo-Agent-Toolkit's AsyncIOProducerConsumerQueue overrides put() with the old loop and inherits get_nowait(). With this PR, a simple producer/consumer on such a subclass (maxsize=2) deadlocks after 3 items: the queue is empty, but full() stays True because _reserved == 2 is never released. In the opposite case, a subclass that wakes putters itself via _wakeup_next(self._putters) drives _reserved negative, and the queue accepts more than maxsize items.

Probably not a blocker, but it might be worth a What's New note (Porting section) along with the full()/qsize() change. If you want to harden the second case, tracking the woken futures in a set instead of a counter keeps _reserved from going negative and makes the _is_shutdown special-casing unnecessary; I tried it locally, and only the tests that compare _reserved with an int needed adjusting.

Nit: the full() docstring in queues.py still says "Return True if there are maxsize items in the queue".

[YvesDup]

This test makes me deeply uncomfortable. Because, IMO, for an asyncio.Queue to be fair, it should not be possible to have a successful put_nowait call with pending or/and woken putters regardless of queue's state.(full or not).
But maybe I have missed something.