Make overload small and reproducible
Set queue capacity to two and offer a third item before consuming any item. This creates a full-buffer boundary through explicit ordering rather than by sending large volumes of time-sensitive traffic. Python queue.Queue supplies synchronization for multi-threaded use, but begin with a single-threaded admission-contract experiment. The procedure is not a benchmark of a production service’s maximum requests per second. It observes which items are accepted, which attempt is rejected and when a slot becomes available again. A controlled burst makes those facts reproducible even on hosts with different CPU speeds and scheduling. Limit the experiment to its own in-memory objects rather than loading an external service.
Handle rejection as an explicit outcome
After put_nowait accepts A and B, attempting C raises Full. Record that rejection instead of swallowing the exception and claiming acceptance. Removing A with get then makes room for C. The slot becomes available because get removes an item; task_done has a different role in tracking completed work. Do not assume that taking an item from a queue means its application processing has finished. In this short program the handling step finishes immediately, so each get is followed by task_done. The final join checks that accepted items have all been acknowledged as finished. Keep admission, removal and completion as three separate transitions when adapting the example to real workers.
import queue
q = queue.Queue(maxsize=2)
q.put_nowait('A')
q.put_nowait('B')
try:
q.put_nowait('C')
except queue.Full:
print('C rejected while full')
else:
raise AssertionError('capacity was not enforced')
assert q.get_nowait() == 'A'
q.task_done()
q.put_nowait('C')
for expected in ('B', 'C'):
assert q.get_nowait() == expected
q.task_done()
q.join()
assert q.empty()
print('A then B then C completed; rejected attempt was explicit')An observed size is not an atomic admission promise
The single-threaded ordering makes occupancy easy to describe. In a concurrent application, however, seeing qsize below capacity does not guarantee that a later put will succeed. Another producer can consume the slot between observation and insertion. Similar cautions apply to empty and full checks. Handle the actual result of put_nowait, or the documented outcome of a timed put, as the admission decision. A monitoring snapshot is not an atomic reservation. When extending the demonstration to multiple producers, retain the queue’s synchronized operation rather than adding a separate “check size, then insert” rule. That rule would recreate the gap the queue abstraction is designed to manage.
Count work outside the buffer too
Capacity two bounds waiting items, not necessarily every in-flight operation. A hundred workers can remove items and then wait on external work while the visible queue remains empty. Two items can also consume substantial memory when payload size is unrestricted. Bound concurrency, input size, database connections and deadlines separately according to the system contract. Creating unlimited waiting threads outside the queue defeats the purpose of local capacity control. Follow the full path from admission through completion and identify where waiting occurs, where rejection occurs and how rejection reaches the caller. An attractive short queue is not proof that the rest of the system has a bounded resource footprint.
If adding timing, retain both useful work and rejection
Before adding threads or simulated processing delays, ensure stalled work cannot leave every participant waiting indefinitely. Consider timed insertion, shutdown signaling and task completion bookkeeping on exceptional paths. Do not silently lose accepted work. A load measurement should distinguish offered, admitted, rejected and completed counts, alongside oldest waiting age. Rejecting more traffic can shorten the queue without improving the user outcome. The present result is a particular transition sequence: accept A and B, reject the first C attempt, remove A, then accept C. That sequence verifies a boundary contract; it does not determine a production throughput limit or an optimal buffer capacity without a separately specified workload experiment.