Rename package circ to queue.

queue/lib.go

@@ -0,0 +1,75 @@
+// Package q implements a non-concurrent queue.
+//
+// # Implementation
+//
+// [Q] is a classic ring buffer. It tracks its head, tail, and length. This
+// makes determining whether the queue is full or empty trivial.
+package queue
+
+// Q is a non-concurrent queue.
+type Q[T any] struct {
+	buf  []T
+	len  int
+	head int
+	tail int
+}
+
+// Make creates a new queue.
+func Make[T any](cap int) Q[T] {
+	buf := make([]T, cap)
+	return Q[T]{buf: buf}
+}
+
+// Capacity returns the total capacity of the queue.
+func (b *Q[T]) Capacity() int {
+	return cap(b.buf)
+}
+
+// Len returns the number of items in the queue.
+func (b *Q[T]) Len() int {
+	return b.len
+}
+
+// CanPush returns true if the queue has space for new items.
+func (b *Q[T]) CanPush() bool {
+	return cap(b.buf)-b.len != 0
+}
+
+// CanPop returns true if the queue has one or more items.
+func (b *Q[T]) CanPop() bool {
+	return b.len != 0
+}
+
+// PopFront returns the front-most item from the queue.
+//
+// If the queue is empty, it panics.
+func (b *Q[T]) PopFront() T {
+	if !b.CanPop() {
+		panic("cannot pop from empty queue")
+	}
+	item := b.buf[b.head]
+	// clear queue slot so as not to hold on to garbage
+	var empty T
+	b.buf[b.head] = empty
+	b.len--
+	b.head++
+	if b.head == cap(b.buf) {
+		b.head = 0
+	}
+	return item
+}
+
+// PushBack adds an item to the end of the queue.
+//
+// If the queue is full, it panics.
+func (b *Q[T]) PushBack(value T) {
+	if !b.CanPush() {
+		panic("cannot push back to full queue")
+	}
+	b.buf[b.tail] = value
+	b.len++
+	b.tail++
+	if b.tail == cap(b.buf) {
+		b.tail = 0
+	}
+}

queue/lib_test.go

@@ -0,0 +1,101 @@
+package queue_test
+
+import (
+	"math/rand"
+	"testing"
+
+	"gogs.humancabbage.net/sam/priorityq/queue"
+)
+
+func TestRepeatPushPop(t *testing.T) {
+	t.Parallel()
+	q := queue.Make[int](4)
+	if q.Capacity() != 4 {
+		t.Errorf("wrong capacity")
+	}
+	for i := 0; i < 50; i++ {
+		q.PushBack(1)
+		q.PushBack(2)
+		q.PushBack(3)
+		q.PushBack(4)
+		if q.Len() != 4 {
+			t.Errorf("wrong length")
+		}
+		checkPop := func(n int) {
+			if v := q.PopFront(); v != n {
+				t.Errorf("popped %d, expected %d", v, n)
+			}
+		}
+		checkPop(1)
+		checkPop(2)
+		checkPop(3)
+		checkPop(4)
+	}
+}
+
+func TestInterleavedPushPop(t *testing.T) {
+	t.Parallel()
+	q := queue.Make[int](4)
+	checkPop := func(n int) {
+		if v := q.PopFront(); v != n {
+			t.Errorf("popped %d, expected %d", v, n)
+		}
+	}
+	q.PushBack(1)
+	q.PushBack(2)
+	q.PushBack(3)
+	checkPop(1)
+	q.PushBack(4)
+	q.PushBack(5)
+	checkPop(2)
+}
+
+func TestEmptyPopPanic(t *testing.T) {
+	defer func() {
+		if r := recover(); r == nil {
+			t.Errorf("popping empty buffer did not panic")
+		}
+	}()
+	t.Parallel()
+	q := queue.Make[int](4)
+	q.PopFront()
+}
+
+func TestFullPushPanic(t *testing.T) {
+	defer func() {
+		if r := recover(); r == nil {
+			t.Errorf("pushing full buffer did not panic")
+		}
+	}()
+	t.Parallel()
+	q := queue.Make[int](1)
+	q.PushBack(1)
+	q.PushBack(2)
+}
+
+func BenchmarkPush(b *testing.B) {
+	q := queue.Make[int](b.N)
+	rs := rand.NewSource(0)
+	r := rand.New(rs)
+	items := make([]int, b.N)
+	for i := 0; i < b.N; i++ {
+		items[i] = r.Int()
+	}
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		q.PushBack(items[i])
+	}
+}
+
+func BenchmarkPop(b *testing.B) {
+	q := queue.Make[int](b.N)
+	rs := rand.NewSource(0)
+	r := rand.New(rs)
+	for i := 0; i < b.N; i++ {
+		q.PushBack(r.Int())
+	}
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		q.PopFront()
+	}
+}