Queue Lifecycle
Last updated
This page explains the three queue states, which calls each state allows, and how Shutdown drains the heap within a deadline.
Queue State
State is an atomic.Uint32, and every transition goes through CompareAndSwap.
| State | Entered By | Enqueue |
Start |
Shutdown |
|---|---|---|---|---|
| Created | New |
Allowed (tasks wait) | Moves to Running | Moves to Closed |
| Running | Start |
Allowed | queue already started |
Moves to Closed |
| Closed | Shutdown |
staging queue is closed |
queue already closed |
Returns nil |
Shutdown
In the Closed state Shutdown lets workers keep popping until the heap is empty, then cancels the root ctx. If the Shutdown ctx expires first, it cancels the root ctx immediately and returns shutdown timeout: N tasks remaining.
| Situation | Result |
|---|---|
| Heap drains before the deadline | Every queued task runs; returns nil |
| Deadline expires first | Running and still-queued tasks get a cancelled ctx; returns shutdown timeout: N tasks remaining |
| Called again | Returns nil immediately |
Called before Start |
Moves to Closed and returns nil; queued tasks never run |