Scan method on the LRU to iterate over the keys and values

[iuga]

Overview

Scanning the key values in an LRU cache allows you to efficiently manage, analyze, and manipulate the cached data. By scanning, you can identify which keys are still relevant, which ones can be evicted, and how to optimize cache performance or resource utilization.

Important

As we are utilizing the latest Golang iterators, the minimum required Go version for this package is now v1.23.

Use Cases

Cache Preloading (Warm-up): In scenarios where anticipated high traffic or load spikes are expected, scanning the cache keys can identify critical data that should be retained or preloaded. This process, known as cache warm-up, ensures that essential data is readily available, reducing latency and improving system performance during peak times.
Usage Analytics and Cache Tuning: Regularly scanning the cache keys provides valuable insights into data access patterns and cache utilization. By analyzing which keys are frequently accessed or close to eviction, it is possible to fine-tune cache parameters, such as size or time-to-live (TTL)

Usage

Scan() returns an iterator that yields current non-expired items from the cache. It iterates over a snapshot of keys taken at the beginning of iteration, checking each key's existence and expiration before yielding its associated value.

for key, value := range lru.Scan() {
  fmt.Println("Items ~>", key, value)
}

Benchmarks

Average times to Scan and extract all the keys from the cache based on 5000 iterations:

goos: darwin
goarch: amd64
cpu: Intel(R) Core(TM) i5-1038NG7 CPU @ 2.00GHz

Key Count	min	median	average	max
1000	13.05µs	51.32µs	62.30µs	455.15µs
100000	77.50µs	407.91µs	595.30µs	27145.62µs
1000000	526.71µs	2678.91µs	2902.60µs	18077.27µs
10000000	164.99µs	10713.59µs	11131.20µs	82050.29µs

[coxley]

Nice! Looks reasonable to me.

There have definitely been a few times where I've wanted to scan the LRU.

[coxley]

Bit shift values on init, but normie numbers on assert? :)

[iuga]

I'm full of complexities and contradictions

[coxley]

Also whoa. TIL that Github Markdown supports admonitions???

[coxley]

@iuga : You can ignore G115 in golangci-lint. People are adding it to their default exclusion lists lately because it's a pretty big overstep in some cases: golangci/golangci-lint#4941