From c1785e3269d27571dcbb190223898be5ede99d0f Mon Sep 17 00:00:00 2001 From: adrianbrad Date: Tue, 21 Apr 2026 11:42:05 +0300 Subject: [PATCH] docs(readme): add 'choosing a queue' decision table --- README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.md b/README.md index 2706893..5b6f02c 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,7 @@ Benchmarks and Example tests can be found in this package. * [queue](#queue) * [Installation](#installation) * [Import](#import) + * [Choosing a queue](#choosing-a-queue) * [Usage](#usage) * [Queue Interface](#queue-interface) * [Blocking Queue](#blocking-queue) @@ -54,6 +55,16 @@ To use this package in your project, you can import it as follows: import "github.com/adrianbrad/queue" ``` +## Choosing a queue + +| Queue | Ordering | Capacity | Blocks? | Pick this when… | +|------------|---------------------|-----------------------------------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------| +| `Blocking` | FIFO | Optional; `Offer` errors on full | Yes — `OfferWait`, `GetWait`, `PeekWait` | You want a classic producer–consumer queue with backpressure and blocking semantics. | +| `Priority` | Custom (less func) | Optional; `Offer` errors on full | No | Order depends on a computed value — smallest deadline, highest score, lexicographic, etc. | +| `Circular` | FIFO | Required; `Offer` **overwrites the oldest** | No | You want fixed memory and the most recent N items; dropping older entries is acceptable. | +| `Linked` | FIFO | None (unbounded) | No | You need an unbounded FIFO and don't want to pick a capacity up front. | +| `Delay` | By deadline | Optional; `Offer` errors on full | `GetWait` sleeps until the head's deadline passes | Items should become available at a future time — timers, retry scheduling, TTL expiry. | + ## Usage ### Queue Interface