A lightweight, generic, production-ready FIFO queue implementation for Go.
Built using a circular buffer for constant-time queue operations, automatic growth, and zero external dependencies.
- Generic (
Queue[T]) - FIFO semantics
- Circular buffer implementation
- Automatic capacity growth
- Zero external dependencies
- Memory-safe dequeue and clear operations
- Fully tested
- Benchmarked
- Fuzz tested
go get github.com/raoamogh/queue-go- Go 1.22+
package main
import (
"fmt"
"github.com/<username>/queue-go"
)
func main() {
q := queue.New[int]()
q.Enqueue(10)
q.Enqueue(20)
q.Enqueue(30)
v, _ := q.Dequeue()
fmt.Println(v)
v, _ = q.Peek()
fmt.Println(v)
}Output
10
20
New[T any]() *Queue[T]
NewWithCapacity[T any](capacity int) *Queue[T]Enqueue(value T)
Dequeue() (T, error)
Peek() (T, error)
Clear()Len() int
Cap() int
Empty() boolvar ErrEmptyReturned by:
Dequeue()Peek()
when the queue is empty.
| Operation | Complexity |
|---|---|
| Enqueue | O(1) amortized |
| Dequeue | O(1) |
| Peek | O(1) |
| Len | O(1) |
| Cap | O(1) |
| Empty | O(1) |
| Clear | O(n) |
The queue is implemented using a dynamically growing circular buffer.
Unlike slice-based queues, dequeue operations do not shift elements.
Growth preserves FIFO ordering while minimizing allocations.
Removed elements are zeroed before being released to avoid retaining references and to assist Go's garbage collector.
Run benchmarks locally:
go test -bench=. -benchmemExample output:
BenchmarkQueue/Enqueue-16 xxxxx ns/op
BenchmarkQueue/Dequeue-16 xxxxx ns/op
BenchmarkQueue/Peek-16 xxxxx ns/op
BenchmarkQueue/EnqueueDequeue-16 xxxxx ns/op
BenchmarkQueue/Growth-16 xxxxx ns/op
BenchmarkQueue/LargeFIFO-16 xxxxx ns/op
BenchmarkQueue/Clear-16 xxxxx ns/op
Benchmark numbers depend on hardware and Go version.
Run unit tests:
go test ./...Run benchmarks:
go test -bench=. -benchmemRun the race detector:
go test -race ./...Run fuzz tests:
go test -fuzz=FuzzQueue- Small API surface
- Predictable performance
- Zero dependencies
- Generic implementation
- Production-ready code
- Idiomatic Go
- Easy to read and maintain
This package intentionally does not provide:
- Thread safety
- Lock-free algorithms
- Blocking queues
- Priority queues
- Double-ended queues (deque)
- Persistent or disk-backed queues
- Serialization
- Concurrent producers/consumers
These concerns are better handled by dedicated packages.
This project follows Semantic Versioning.
MAJOR.MINOR.PATCH
- MAJOR for breaking API changes
- MINOR for backward-compatible features
- PATCH for bug fixes and performance improvements
- Generic queue
- Circular buffer
- Automatic growth
- Unit tests
- Benchmarks
- Fuzz tests
- GitHub Actions
- Documentation
- Iterator support (if justified)
- Optional capacity shrink API
- Additional benchmark suites
- Performance tuning based on profiling
New features will only be added if they preserve the library's simplicity and API stability.
Contributions are welcome.
Before submitting a pull request:
- Run all tests
- Run benchmarks
- Run the race detector
- Keep the public API minimal
- Maintain backwards compatibility where possible
MIT License.