queue

README

Queue

This package provides a generic, thread-safe FIFO queue implementation for Go, supporting any type with automatic dynamic resizing.

Features

• Generic: Works with any type using Go generics (Queue[T any])
• Thread-Safe: All operations are protected by mutex for concurrent access
• Dynamic Resizing: Automatic growth (2x) and shrinking (0.5x) based on usage
• Circular Buffer: Efficient O(1) enqueue/dequeue operations with minimal memory overhead
• Memory Efficient: Zero-value clearing prevents memory leaks
• FIFO Semantics: First-In-First-Out queue behavior
• Error Handling: Proper error types for empty queue operations

API

• NewQueue: Creates a new queue with specified initial capacity
• Enqueue: Adds an item to the end of the queue
• Dequeue: Removes and returns the front item (returns error if empty)
• Peek: Returns the front item without removing it (returns error if empty)
• Size: Returns the current number of elements in the queue
• Capacity: Returns the queue's current capacity
• IsEmpty: Returns true if the queue contains no elements

Performance

• Enqueue: ~28ns/op with minimal allocations
• Dequeue: ~11ns/op with minimal allocations
• Peek: ~5ns/op with zero allocations
• Memory: Minimal heap allocations during normal operations

Examples

For comprehensive examples of each function, please check out EXAMPLES.md

---

Documentation

Index

• Constants
• Variables
• type Queue
  • func NewQueue[T any](capacity int) *Queue[T]
  • func (q *Queue[T]) Capacity() int
  • func (q *Queue[T]) Dequeue() (T, error)
  • func (q *Queue[T]) Enqueue(item T)
  • func (q *Queue[T]) IsEmpty() bool
  • func (q *Queue[T]) Peek() (T, error)
  • func (q *Queue[T]) Size() int

Constants

const (
	// MinCapacity is the initial capacity for a new queue.
	MinCapacity = 16
)

Variables

var ErrEmptyQueue = errors.New("queue is empty")

ErrEmptyQueue is returned when the queue is empty.

Types

type Queue

type Queue[T any] struct {
	// contains filtered or unexported fields
}

Queue is a generic, thread-safe FIFO queue implementation. It uses a circular buffer internally and automatically grows or shrinks as needed.

Type Parameters:

T: The type of elements stored in the queue.

func NewQueue

func NewQueue[T any](capacity int) *Queue[T]

NewQueue creates a new Queue with the given capacity.

func (*Queue[T]) Capacity

func (q *Queue[T]) Capacity() int

Capacity returns the queue's capacity.

func (*Queue[T]) Dequeue

func (q *Queue[T]) Dequeue() (T, error)

Dequeue removes and returns the front item. Returns ErrEmptyQueue if the queue is empty.

func (*Queue[T]) Enqueue

func (q *Queue[T]) Enqueue(item T)

Enqueue adds an item to the end of the queue.

func (*Queue[T]) IsEmpty

func (q *Queue[T]) IsEmpty() bool

IsEmpty returns true if the queue is empty.

func (*Queue[T]) Peek

func (q *Queue[T]) Peek() (T, error)

Peek returns the front item without removing it. Returns ErrEmptyQueue if the queue is empty.

func (*Queue[T]) Size

func (q *Queue[T]) Size() int

Size returns the number of items in the queue.