Files
2026-11-13 09:15:13 +08:00

361 lines
9.2 KiB
Go

package cache
import (
"context"
"sync"
"sync/atomic"
"time"
)
// Interface defines the operations a cache must support.
type Interface interface {
// Set adds a value to the cache with the default TTL.
Set(ctx context.Context, key string, value any)
// SetWithTTL adds a value to the cache with a custom TTL.
SetWithTTL(ctx context.Context, key string, value any, ttl time.Duration)
// Get retrieves a value from the cache.
Get(ctx context.Context, key string) (any, bool)
// Delete removes a value from the cache.
Delete(ctx context.Context, key string)
// Clear removes all values from the cache.
Clear(ctx context.Context)
// Size returns the number of items in the cache.
Size() int64
// Close stops all background tasks and releases resources.
Close() error
}
// item represents a cached value with metadata.
type item struct {
value any
expiration time.Time
size int // Approximate size in bytes
}
// Config contains options for configuring a cache.
type Config struct {
// DefaultTTL is the default time-to-live for cache entries.
DefaultTTL time.Duration
// CleanupInterval is how often the cache runs cleanup.
CleanupInterval time.Duration
// MaxItems is the maximum number of items allowed in the cache.
MaxItems int
// OnEviction is called when an item is evicted from the cache.
// It runs synchronously in the goroutine performing the eviction, which may
// be the background cleanup goroutine. It must not call Close synchronously:
// Close waits for that goroutine to exit. To request closure from a callback,
// start Close in a separate goroutine and return without waiting for it.
OnEviction func(key string, value any)
}
// DefaultConfig returns a default configuration for the cache.
func DefaultConfig() Config {
return Config{
DefaultTTL: 10 * time.Minute,
CleanupInterval: 5 * time.Minute,
MaxItems: 1000,
OnEviction: nil,
}
}
// Cache is a thread-safe in-memory cache with TTL and memory management.
type Cache struct {
itemCount atomic.Int64 // Use atomic operations to track item count
data sync.Map // stores *item; pointer identity guards removals
config Config
stopChan chan struct{}
closedChan chan struct{}
closed atomic.Bool
}
// New creates a new memory cache with the given configuration.
func New(config Config) *Cache {
c := &Cache{
config: config,
stopChan: make(chan struct{}),
closedChan: make(chan struct{}),
}
go c.cleanupLoop()
return c
}
// NewDefault creates a new memory cache with default configuration.
func NewDefault() *Cache {
return New(DefaultConfig())
}
// Set adds a value to the cache with the default TTL.
func (c *Cache) Set(ctx context.Context, key string, value any) {
c.SetWithTTL(ctx, key, value, c.config.DefaultTTL)
}
// SetWithTTL adds a value to the cache with a custom TTL.
func (c *Cache) SetWithTTL(_ context.Context, key string, value any, ttl time.Duration) {
// Estimate size of the item (very rough approximation).
size := estimateSize(value)
entry := &item{
value: value,
expiration: time.Now().Add(ttl),
size: size,
}
for {
if old, ok := c.data.Load(key); ok {
// Replacing an existing entry does not change the count.
if c.data.CompareAndSwap(key, old, entry) {
break
}
continue
}
// Count the new entry before it is published, so a concurrent removal
// cannot decrement a count that has not been incremented.
(&c.itemCount).Add(1)
if _, loaded := c.data.LoadOrStore(key, entry); !loaded {
break
}
// Another writer published the key first. Undo the reservation and retry.
(&c.itemCount).Add(-1)
}
// If we're over the max items, clean up old items.
if c.config.MaxItems > 0 && (&c.itemCount).Load() > int64(c.config.MaxItems) {
c.cleanupOldest()
}
}
// Get retrieves a value from the cache.
func (c *Cache) Get(_ context.Context, key string) (any, bool) {
for {
value, ok := c.data.Load(key)
if !ok {
return nil, false
}
itm, ok := value.(*item)
if !ok {
// If the value is not of type *item, it means it was corrupted or not set correctly.
if _, loaded := c.data.LoadAndDelete(key); loaded {
(&c.itemCount).Add(-1)
}
return nil, false
}
if !time.Now().After(itm.expiration) {
return itm.value, true
}
// Only account for the removal if we removed the exact entry we
// observed. A concurrent Set may have already replaced it with a
// fresher entry, which must survive.
if c.data.CompareAndDelete(key, value) {
(&c.itemCount).Add(-1)
if c.config.OnEviction != nil {
c.config.OnEviction(key, itm.value)
}
return nil, false
}
// The expired entry was replaced while we looked at it; read the fresher one.
}
}
// Delete removes a value from the cache.
func (c *Cache) Delete(_ context.Context, key string) {
if value, loaded := c.data.LoadAndDelete(key); loaded {
(&c.itemCount).Add(-1)
if c.config.OnEviction != nil {
if itm, ok := value.(*item); ok {
c.config.OnEviction(key, itm.value)
}
}
}
}
// Clear removes all values from the cache.
func (c *Cache) Clear(_ context.Context) {
c.data.Range(func(key, value any) bool {
if _, loaded := c.data.LoadAndDelete(key); loaded {
(&c.itemCount).Add(-1)
if c.config.OnEviction != nil {
itm, ok := value.(*item)
if ok {
if keyStr, ok := key.(string); ok {
c.config.OnEviction(keyStr, itm.value)
}
}
}
}
return true
})
}
// Size returns the number of items in the cache.
func (c *Cache) Size() int64 {
return (&c.itemCount).Load()
}
// Close stops the cache cleanup goroutine.
// Every caller waits for cleanup to finish. Close must not be called
// synchronously from OnEviction; see Config.OnEviction.
func (c *Cache) Close() error {
if c.closed.CompareAndSwap(false, true) {
close(c.stopChan)
}
<-c.closedChan // Every caller waits for the cleanup goroutine to exit.
return nil
}
// cleanupLoop periodically cleans up expired items.
func (c *Cache) cleanupLoop() {
ticker := time.NewTicker(c.config.CleanupInterval)
defer func() {
ticker.Stop()
close(c.closedChan)
}()
for {
select {
case <-ticker.C:
c.cleanup()
case <-c.stopChan:
return
}
}
}
// cleanup removes expired items.
func (c *Cache) cleanup() {
evicted := make(map[string]any)
count := 0
c.data.Range(func(key, value any) bool {
itm, ok := value.(*item)
if !ok {
return true
}
if time.Now().After(itm.expiration) {
// CompareAndDelete so a concurrently re-set fresher entry is
// neither removed nor counted.
if !c.data.CompareAndDelete(key, value) {
return true
}
count++
if c.config.OnEviction != nil {
if keyStr, ok := key.(string); ok {
evicted[keyStr] = itm.value
}
}
}
return true
})
if count > 0 {
(&c.itemCount).Add(-int64(count))
// Call eviction callbacks outside the loop to avoid blocking the range
if c.config.OnEviction != nil {
for k, v := range evicted {
c.config.OnEviction(k, v)
}
}
}
}
// cleanupOldest removes the oldest items if we're over the max items.
//
// itemCount can transiently over-count while other writers hold reservations
// for keys they have not published yet, so the decision to evict is based on
// the entries actually in the map, counted during the same scan that picks
// the eviction candidates.
func (c *Cache) cleanupOldest() {
// Remove 20% of max items at once
threshold := max(c.config.MaxItems/5, 1)
// Find the oldest items
type keyExpPair struct {
key string
entry *item
expiration time.Time
}
candidates := make([]keyExpPair, 0, threshold)
published := int64(0)
c.data.Range(func(key, value any) bool {
itm, ok := value.(*item)
if !ok {
return true
}
published++
if keyStr, ok := key.(string); ok && len(candidates) < threshold {
candidates = append(candidates, keyExpPair{keyStr, itm, itm.expiration})
return true
}
// Find the newest item in candidates
newestIdx := 0
for i := 1; i < len(candidates); i++ {
if candidates[i].expiration.After(candidates[newestIdx].expiration) {
newestIdx = i
}
}
// Replace it if this item is older
if itm.expiration.Before(candidates[newestIdx].expiration) {
candidates[newestIdx] = keyExpPair{key.(string), itm, itm.expiration}
}
return true
})
// Not actually over the limit: the counter was inflated by in-flight reservations.
if published <= int64(c.config.MaxItems) {
return
}
// Delete the oldest items
deletedCount := 0
for _, candidate := range candidates {
// CompareAndDelete so an entry re-set or already removed since the
// scan is neither removed nor counted.
if !c.data.CompareAndDelete(candidate.key, candidate.entry) {
continue
}
deletedCount++
if c.config.OnEviction != nil {
c.config.OnEviction(candidate.key, candidate.entry.value)
}
}
// Update count
if deletedCount > 0 {
(&c.itemCount).Add(-int64(deletedCount))
}
}
// estimateSize attempts to estimate the memory footprint of a value.
func estimateSize(value any) int {
switch v := value.(type) {
case string:
return len(v) + 24 // base size + string overhead
case []byte:
return len(v) + 24 // base size + slice overhead
case map[string]any:
return len(v) * 64 // rough estimate
default:
return 64 // default conservative estimate
}
}