perf(linked): recycle nodes via internal free list + refresh README benchmarks (#58)

* perf(linked): recycle popped nodes via internal free list

Offer allocated a fresh *node[T] every call and Get handed popped
nodes to the GC. In the steady-state offer/get pattern that's one
allocation per cycle — visible in the benchmark as 16 B/op / 1 alloc.

Maintain an internal free stack of popped nodes (capped at 64 to avoid
retaining memory after a large drain). Offer pulls from it first,
Get pushes onto it. No cross-goroutine pool contention because the
list lives under the queue's existing lock.

Benchmark on darwin/arm64, M4 Pro:

    before  BenchmarkLinkedQueue/Get_Offer-12   19.70 ns/op  16 B/op  1 allocs/op
    after   BenchmarkLinkedQueue/Get_Offer-12   14.75 ns/op   0 B/op  0 allocs/op

    before  BenchmarkLinkedQueue/Offer-12       21.71 ns/op  16 B/op  1 allocs/op
    after   BenchmarkLinkedQueue/Offer-12       22.42 ns/op  16 B/op  1 allocs/op

Offer-only pattern keeps the same alloc profile (free list stays
empty). Peek unchanged. Get no longer issues an allocation in the
common case.

Refs #47

* docs(readme): refresh benchmarks post-fixes

Numbers taken on an Apple M4 Pro (darwin/arm64), go test -bench=. -count=3.
The old table was from October 2023 on an 8-core machine and predates
all the recent fixes (pointer-retention, Broadcast-vs-Signal, heap.Pop
correction, and the linked queue's node free list).

Most notable change: LinkedQueue/Get_Offer drops from 16 B / 1 alloc
to 0 B / 0 allocs.

* docs(readme): drop hardware details from benchmark block

* docs(readme): drop MarshalJSON from benchmark table

* test(linked): cover free-list reuse and cap-reached branches

The node free list added in this branch introduced two new branches
that the existing tests didn't hit — "Offer after Get reuses a
recycled node" and "drain past freeCap stops growing the free list".
Coverage fell to 98.4% and the 100% gate failed.

Add a dedicated sub-test that exercises both paths. No observable
behaviour change.

* test(linked): split recycle coverage test to keep gocognit under 20

Author: adrianbrad

README.md

@@ -269,19 +269,19 @@ func main() {
 
 ## Benchmarks 
 
-Results as of October 2023.
+Run locally with `go test -bench=. -benchmem -benchtime=3s -count=3`. Reported numbers are per-operation timings and allocations; absolute values vary by hardware, but the shape (zero-alloc reads everywhere, zero-alloc offer/get for Circular and Linked) should be stable.
 
 ```text
-BenchmarkBlockingQueue/Peek-8           84873882                13.98 ns/op            0 B/op          0 allocs/op
-BenchmarkBlockingQueue/Get_Offer-8      27135865                47.00 ns/op           44 B/op          0 allocs/op
-BenchmarkBlockingQueue/Offer-8          53750395                25.40 ns/op           43 B/op          0 allocs/op
-BenchmarkCircularQueue/Peek-8           86001980                13.76 ns/op            0 B/op          0 allocs/op
-BenchmarkCircularQueue/Get_Offer-8      32379159                36.83 ns/op            0 B/op          0 allocs/op
-BenchmarkCircularQueue/Offer-8          63956366                18.77 ns/op            0 B/op          0 allocs/op
-BenchmarkLinkedQueue/Peek-8             1000000000              0.4179 ns/op           0 B/op          0 allocs/op
-BenchmarkLinkedQueue/Get_Offer-8        61257436                18.48 ns/op           16 B/op          1 allocs/op
-BenchmarkLinkedQueue/Offer-8            38975062                30.74 ns/op           16 B/op          1 allocs/op
-BenchmarkPriorityQueue/Peek-8           86633734                14.02 ns/op            0 B/op          0 allocs/op
-BenchmarkPriorityQueue/Get_Offer-8      29347177                39.88 ns/op            0 B/op          0 allocs/op
-BenchmarkPriorityQueue/Offer-8          40117958                31.37 ns/op           54 B/op          0 allocs/op
+BenchmarkBlockingQueue/Peek                  3.8 ns/op       0 B/op   0 allocs/op
+BenchmarkBlockingQueue/Get_Offer            22.9 ns/op       8 B/op   1 allocs/op
+BenchmarkBlockingQueue/Offer                13.0 ns/op      49 B/op   0 allocs/op
+BenchmarkCircularQueue/Peek                  3.9 ns/op       0 B/op   0 allocs/op
+BenchmarkCircularQueue/Get_Offer            13.9 ns/op       0 B/op   0 allocs/op
+BenchmarkCircularQueue/Offer                 6.5 ns/op       0 B/op   0 allocs/op
+BenchmarkLinkedQueue/Peek                    3.9 ns/op       0 B/op   0 allocs/op
+BenchmarkLinkedQueue/Get_Offer              14.7 ns/op       0 B/op   0 allocs/op
+BenchmarkLinkedQueue/Offer                  22.7 ns/op      16 B/op   1 allocs/op
+BenchmarkPriorityQueue/Peek                  3.9 ns/op       0 B/op   0 allocs/op
+BenchmarkPriorityQueue/Get_Offer            18.1 ns/op       0 B/op   0 allocs/op
+BenchmarkPriorityQueue/Offer                17.1 ns/op      48 B/op   0 allocs/op
 ```

linked.go

@@ -23,8 +23,16 @@ type Linked[T comparable] struct {
 	initialElements []T // initial elements with which the queue was created, allowing for a reset to its original state if needed.
 	// synchronization
 	lock sync.RWMutex
+	// free is a stack of recycled nodes. Offer pulls from here before
+	// allocating; Get pushes onto it. Bounded to freeCap so Clear/Reset
+	// can't cause unbounded retention.
+	free    *node[T]
+	freeLen int
 }
 
+// freeCap is the maximum number of nodes cached for reuse.
+const freeCap = 64
+
 // NewLinked creates a new Linked containing the given elements.
 func NewLinked[T comparable](elements []T) *Linked[T] {
 	queue := &Linked[T]{
@@ -52,14 +60,18 @@ func (lq *Linked[T]) Get() (elem T, _ error) {
 		return elem, ErrNoElementsAvailable
 	}
 
-	value := lq.head.value
-	lq.head = lq.head.next
+	popped := lq.head
+	value := popped.value
+
+	lq.head = popped.next
 	lq.size--
 
 	if lq.isEmpty() {
 		lq.tail = nil
 	}
 
+	lq.recycle(popped)
+
 	return value, nil
 }
 
@@ -73,7 +85,8 @@ func (lq *Linked[T]) Offer(value T) error {
 
 // offer inserts the element into the queue.
 func (lq *Linked[T]) offer(value T) error {
-	newNode := &node[T]{value: value}
+	newNode := lq.acquireNode()
+	newNode.value = value
 
 	if lq.isEmpty() {
 		lq.head = newNode
@@ -87,6 +100,35 @@ func (lq *Linked[T]) offer(value T) error {
 	return nil
 }
 
+// acquireNode pulls a node off the free list or allocates a fresh one.
+func (lq *Linked[T]) acquireNode() *node[T] {
+	if lq.free == nil {
+		return &node[T]{}
+	}
+
+	n := lq.free
+	lq.free = n.next
+	lq.freeLen--
+	n.next = nil
+
+	return n
+}
+
+// recycle zeroes a popped node and returns it to the free list, capped
+// at freeCap to avoid pinning memory after a large drain.
+func (lq *Linked[T]) recycle(n *node[T]) {
+	if lq.freeLen >= freeCap {
+		return
+	}
+
+	var zero T
+
+	n.value = zero
+	n.next = lq.free
+	lq.free = n
+	lq.freeLen++
+}
+
 // Reset sets the queue to its initial state.
 func (lq *Linked[T]) Reset() {
 	lq.lock.Lock()

linked_test.go

@@ -22,6 +22,66 @@ func TestLinked(t *testing.T) {
 	t.Run("Reset", testLinkedReset)
 	t.Run("Iterator", testLinkedIterator)
 	t.Run("MarshalJSON", testLinkedMarshalJSON)
+	t.Run("OfferReusesPoppedNode", testLinkedOfferReusesPoppedNode)
+	t.Run("DrainBeyondFreeCap", testLinkedDrainBeyondFreeCap)
+}
+
+// testLinkedOfferReusesPoppedNode drives the free-list-has-node branch
+// of the internal node recycling.
+func testLinkedOfferReusesPoppedNode(t *testing.T) {
+	t.Parallel()
+
+	linkedQueue := queue.NewLinked([]int{1, 2, 3})
+
+	got, err := linkedQueue.Get()
+	if err != nil || got != 1 {
+		t.Fatalf("get: %d %v", got, err)
+	}
+
+	// This Offer reuses the node just released by Get.
+	if err := linkedQueue.Offer(4); err != nil {
+		t.Fatalf("offer: %v", err)
+	}
+
+	cleared := linkedQueue.Clear()
+	expected := []int{2, 3, 4}
+
+	if !reflect.DeepEqual(expected, cleared) {
+		t.Fatalf("expected %v got %v", expected, cleared)
+	}
+}
+
+// testLinkedDrainBeyondFreeCap drives the cap-reached branch of the
+// internal recycle() so the free list stops growing past its cap.
+func testLinkedDrainBeyondFreeCap(t *testing.T) {
+	t.Parallel()
+
+	// Use a size that exceeds the free-list cap so the cap-reached
+	// branch of recycle() executes.
+	const n = 128
+
+	linkedQueue := queue.NewLinked[int](nil)
+
+	for i := 0; i < n; i++ {
+		if err := linkedQueue.Offer(i); err != nil {
+			t.Fatalf("offer %d: %v", i, err)
+		}
+	}
+
+	for i := 0; i < n; i++ {
+		got, err := linkedQueue.Get()
+		if err != nil {
+			t.Fatalf("get %d: %v", i, err)
+		}
+
+		if got != i {
+			t.Fatalf("get %d: want %d got %d", i, i, got)
+		}
+	}
+
+	if !linkedQueue.IsEmpty() {
+		t.Fatal("queue should be empty")
+	}
 }
 
 func testLinkedGet(t *testing.T) {