Package lfq provides bounded FIFO queue implementations. The package offers multiple queue variants optimized for different producer/consumer patterns: Direct constructors (recommended for most cases): Builder API auto-selects algorithm based on constraints: All queues share the same interface for enqueueing and dequeueing: Pipeline Stage (SPSC): Event Aggregation (MPSC): Work Distribution (SPMC): Worker Pool (MPMC): Three queue flavors are available for different use cases: When to use Indirect: When to use Ptr: The builder selects algorithms based on constraints and Compact() hint: Default (FAA-based, 2n slots for capacity n): With Compact() (CAS-based, n slots for capacity n): FAA (Fetch-And-Add) scales better under high contention but requires 2n physical slots. Use Compact() when memory efficiency is critical. Type-safe builder functions enforce constraints at compile time: Compact() selects CAS-based algorithms with n physical slots (vs 2n for FAA-based default). Use when memory efficiency is more important than contention scalability: SPSC variants already use n slots (Lamport ring buffer) and ignore Compact(). Queues return ErrWouldBlock when operations cannot proceed. This error is sourced from code.hybscloud.com/iox for ecosystem consistency. For semantic error classification (delegates to iox): Capacity rounds up to the next power of 2: Minimum capacity is 2 (already a power of 2). Panic if capacity < 2. FAA-based queues (MPSC, SPMC, MPMC) use a best-effort pre-check before the atomic slot claim. Under high concurrency, up to P−1 additional items (P = number of concurrent producers) may be transiently enqueued beyond Cap(). The 2n physical slot buffer accommodates this safely. Compact (CAS-based) variants enforce a strict capacity bound. Length is intentionally not provided because accurate counts in lock-free algorithms require expensive cross-core synchronization. Track counts in application logic when needed. All queue operations are thread-safe within their access pattern constraints: Violating these constraints (e.g., multiple producers on SPSC) causes undefined behavior including data corruption and races. FAA-based queues (MPMC, SPMC, MPSC) include a threshold mechanism to prevent livelock. This mechanism may cause Dequeue to return ErrWouldBlock even when items remain, waiting for producer activity to reset the threshold. For graceful shutdown scenarios where producers have finished but consumers need to drain remaining items, use the Drainer interface: After Drain is called, Dequeue skips threshold checks, allowing consumers to fully drain the queue. Drain is a hint — the caller must ensure no further Enqueue calls will be made. SPSC queues do not implement Drainer as they have no threshold mechanism. The type assertion naturally handles this case. Go's race detector is not designed for lock-free algorithm verification. The race detector tracks explicit synchronization primitives (mutex, channels, WaitGroup) but cannot observe happens-before relationships established through atomic memory orderings (acquire-release semantics). Lock-free queues use sequence numbers with acquire-release semantics to protect non-atomic data fields. These algorithms are correct, but the race detector may report false positives because it cannot track synchronization provided by atomic operations on separate variables. For lock-free algorithm correctness verification, use: Tests incompatible with race detection are excluded via //go:build !race. This package uses code.hybscloud.com/iox for semantic errors, code.hybscloud.com/atomix for atomic primitives with explicit memory ordering, and code.hybscloud.com/spin for CPU pause instructions. Example_backpressure demonstrates handling backpressure with a full queue. Example_batchProcessing demonstrates collecting items into batches. Example_bufferPool demonstrates using Indirect queue for buffer pool management. Example_compactMode demonstrates compact mode for memory-constrained scenarios. Example_pipeline demonstrates a multi-stage pipeline using SPSC queues. Example_workerPool demonstrates a worker pool pattern using MPMC.