Support Iterator for fastcache

[ehnuje]

• Spawned from Iterator support? #43 - Iterator support?
• I've checked the previous iterator-like implementation, Add VisitAllEntries method to iterate all entries in cache. #3
• This implementation avoids iterating the whole cache from a single function call. Instead, it copies keys from a bucket, not whole keys from a cache. And then it uses the copied key to retrieve the value from the cache.

func TestCacheIterator(t *testing.T) {
	c := New(1024)
	defer c.Reset()

	numEntries := 100
	keyValMap := make(map[string][]byte)
	for i := 0; i < numEntries; i++ {
		k := []byte(fmt.Sprintf("key %d", i))
		v := []byte(fmt.Sprintf("value %d", i))
		c.Set(k, v)
		keyValMap[string(k)] = v
		vv := c.Get(nil, k)
		if string(vv) != string(v) {
			t.Fatalf("unexpected value for key %q; got %q; want %q", k, vv, v)
		}
	}

	itr := c.Iterator()
	for itr.SetNext() {
		entry, err := itr.Value()
		if err != nil {
			t.Fatal("unexpected error from itr.Value()", "err", err)
		}

		val, exist := keyValMap[string(entry.key)]
		if !exist {
			t.Fatal("failed to retrieve an entry from cache which should exist")
		}
		if !bytes.Equal(val, entry.value) {
			t.Fatalf("value from iterator is not the same as the expected one for key %q; got %q; want %q",
				entry.key, entry.value, val)
		}
	}
}

[elimist3]

LTGM!

From the looks of it, this is a highly desirable feature and this PR looks pretty solid!

[hhhhax]

When the number of traversals I traverse is large enough, it will cause the array to go out of bounds and cause a panic. Can you help me check it out?
`c := New(2 * 1024 * 1024 * 1024 * 1024)
defer c.Reset()

numEntries := 10000000
keyValMap := make(map[string][]byte)
for i := 0; i < numEntries; i++ {
	k := []byte(fmt.Sprintf("key %d", i))
	v := []byte(fmt.Sprintf("value %d", i))
	c.Set(k, v)
	keyValMap[string(k)] = v
	vv := c.Get(nil, k)
	if string(vv) != string(v) {
		t.Fatalf("unexpected value for key %q; got %q; want %q", k, vv, v)
	}
}

go func() {
	for {
		numEntries := 10000000
		keyValMap := make(map[string][]byte)
		for i := 0; i < numEntries; i++ {
			k := []byte(fmt.Sprintf("key %d", i))
			v := []byte(fmt.Sprintf("value %d", i))
			keyValMap[string(k)] = v
			vv := c.Get(nil, k)
			if string(vv) != string(v) {
				t.Fatalf("unexpected value for key %q; got %q; want %q", k, vv, v)
			}
		}

	}
}()

for {
	time.Sleep(1 * time.Second)
	itr := c.Iterator()
	count := 0
	for itr.HasNext() {
		count++
		_, _, err := itr.Value()
		if err != nil {
			t.Fatal("unexpected error from itr.Value()", "err", err)
		}

		//val, exist := keyValMap[string(key)]
		//if !exist {
		//	t.Fatal("failed to retrieve an entry from cache which should exist")
		//}
		//if !bytes.Equal(val, value) {
		//	t.Fatalf("value from iterator is not the same as the expected one for key %q; got %q; want %q",
		//		key, value, val)
		//}
	}
	fmt.Printf("count:%v\n", count)
}`

[hhhhax]

This may cause the array to go out of bounds and generate Panic

[hhhhax]

Adding this line of code may solve the problem, can you help me take a look? idx = idx % chunkSize

[HT4w5]

Yes, I think idx %= chunkSize should be added like in (*bucket).Get().

FYI, here is the panic log:

2026/03/31 08:19:17 [Recovery] 2026/03/31 - 08:19:17 panic recovered:
runtime error: slice bounds out of range [:144261] with capacity 65536

[HT4w5]

I believe the condition should be:

gen == bGen && idx < b.idx || gen+1 == bGen && idx >= b.idx || gen == maxGen && bGen == 1 && idx >= b.idx

gen == maxGen && bGen == 1 && idx >= b.idx is the situation where maxGen is reached on the last wrap and the current generation is reset to 1.

[HT4w5]

Consider storing (hash, idx) pairs in iterator instead of bucket keys? Let SetNext() verify key hash on retrieval?

This removes the necessity of copying all the keys from the bucket.

[HT4w5]

Currently SetNext() allocates a new slice when retrieving the value. Consider using a single GetNext(kDst []byte, vDst []byte) ([]byte, []byte, bool) similar to (*Cache).Get for zero-copy?