fixup! Further pursue of perfection.

cache_optimized.go

@@ -5,67 +5,72 @@ import (
 	"time"
 )
 
-// MaxKeyLength defines the maximum allowed length for cache keys
+// MaxKeyLength defines the maximum allowed cache key length
 // to prevent memory exhaustion from excessively long keys.
 const MaxKeyLength = 256
 
-// OptimizedCacheEntry represents a single cache entry with embedded LRU linked list pointers.
-// This design eliminates the need for separate data structures (list.List and map[string]*list.Element)
-// and reduces memory overhead by approximately 66% compared to traditional implementations.
+// OptimizedCacheEntry represents a cache entry in the optimized cache implementation.
+// It uses intrusive linked list design to eliminate separate list nodes,
+// reducing memory overhead by approximately 66% compared to traditional implementations.
 type OptimizedCacheEntry struct {
-	Value     interface{}
 	ExpiresAt time.Time
+	Value     interface{}
+	prev      *OptimizedCacheEntry
+	next      *OptimizedCacheEntry
 	Key       string
-
-	// Embedded doubly-linked list pointers for LRU ordering
-	prev, next *OptimizedCacheEntry
 }
 
-// OptimizedCache provides a memory-efficient, thread-safe cache with LRU eviction policy.
-// It uses a single map with entries containing embedded doubly-linked list pointers,
-// eliminating the memory overhead of maintaining separate data structures.
+// OptimizedCache provides a memory-efficient, thread-safe cache with LRU eviction.
+// It uses an intrusive doubly-linked list design for O(1) LRU operations.
 // The cache supports both item count and memory size limits.
 type OptimizedCache struct {
-	items               map[string]*OptimizedCacheEntry
-	head, tail          *OptimizedCacheEntry // LRU sentinel nodes
-	cleanupTask         *BackgroundTask
-	logger              *Logger
-	maxSize             int
-	maxMemoryBytes      int64 // Memory budget limit
-	currentMemoryBytes  int64 // Current estimated memory usage
+	// items maps keys to cache entries
+	items map[string]*OptimizedCacheEntry
+	// head, tail are sentinel nodes for the LRU doubly-linked list
+	head, tail *OptimizedCacheEntry
+	// cleanupTask handles background cleanup of expired entries
+	cleanupTask *BackgroundTask
+	// logger for debugging and monitoring
+	logger *Logger
+	// maxSize limits the number of cache entries
+	maxSize int
+	// maxMemoryBytes limits total memory usage in bytes
+	maxMemoryBytes int64
+	// currentMemoryBytes tracks estimated memory usage
+	currentMemoryBytes int64
+	// autoCleanupInterval defines cleanup frequency
 	autoCleanupInterval time.Duration
-	mutex               sync.RWMutex
+	// mutex provides thread safety for all operations
+	mutex sync.RWMutex
 }
 
-// NewOptimizedCache creates a new memory-efficient cache with default settings.
-// It uses the default maximum size and no memory limit.
+// NewOptimizedCache creates a new optimized cache with default settings.
+// It uses the default maximum size and 64MB memory limit.
 func NewOptimizedCache() *OptimizedCache {
 	return NewOptimizedCacheWithConfig(DefaultMaxSize, 0, nil)
 }
 
-// NewOptimizedCacheWithConfig creates a cache with specified configuration.
-//
+// NewOptimizedCacheWithConfig creates a new optimized cache with custom configuration.
 // Parameters:
-//   - maxSize: Maximum number of items in the cache.
-//   - maxMemoryMB: Maximum memory usage in megabytes (0 for default 64MB).
-//   - logger: Logger instance for debug output (nil for no-op logger).
+//   - maxSize: Maximum number of entries (0 uses default)
+//   - maxMemoryMB: Memory limit in megabytes (0 uses 64MB default)
+//   - logger: Logger instance for debugging (nil creates no-op logger)
 //
 // Returns:
-//   - A new OptimizedCache instance.
+//   - A new OptimizedCache instance
 func NewOptimizedCacheWithConfig(maxSize int, maxMemoryMB int, logger *Logger) *OptimizedCache {
 	if logger == nil {
-		logger = newNoOpLogger()
+		logger = GetSingletonNoOpLogger()
 	}
 
-	// Create sentinel nodes for the doubly-linked list
 	head := &OptimizedCacheEntry{}
 	tail := &OptimizedCacheEntry{}
 	head.next = tail
 	tail.prev = head
 
-	maxMemoryBytes := int64(maxMemoryMB) * 1024 * 1024 // Convert MB to bytes
+	maxMemoryBytes := int64(maxMemoryMB) * 1024 * 1024
 	if maxMemoryBytes == 0 {
-		maxMemoryBytes = 64 * 1024 * 1024 // Default 64MB
+		maxMemoryBytes = 64 * 1024 * 1024
 	}
 
 	c := &OptimizedCache{
@@ -74,7 +79,7 @@ func NewOptimizedCacheWithConfig(maxSize int, maxMemoryMB int, logger *Logger) *
 		tail:                tail,
 		maxSize:             maxSize,
 		maxMemoryBytes:      maxMemoryBytes,
-		autoCleanupInterval: 5 * time.Minute,
+		autoCleanupInterval: 2 * time.Minute,
 		logger:              logger,
 	}
 
@@ -82,16 +87,14 @@ func NewOptimizedCacheWithConfig(maxSize int, maxMemoryMB int, logger *Logger) *
 	return c
 }
 
-// Set adds or updates an item in the cache with the specified expiration.
-// It validates key length and enforces both item count and memory limits.
-// When limits are exceeded, the least recently used items are evicted.
-//
+// Set stores a value in the optimized cache with memory tracking and LRU management.
+// Keys longer than MaxKeyLength are rejected to prevent memory exhaustion.
+// If the cache exceeds size or memory limits, least recently used items are evicted.
 // Parameters:
-//   - key: The cache key (must be <= MaxKeyLength).
-//   - value: The value to cache.
-//   - expiration: Time until the item expires.
+//   - key: The cache key (must be <= MaxKeyLength)
+//   - value: The value to store
+//   - expiration: Time until the item expires
 func (c *OptimizedCache) Set(key string, value interface{}, expiration time.Duration) {
-	// Validate key length to prevent memory bloat
 	if len(key) > MaxKeyLength {
 		c.logger.Debugf("Cache key too long (%d > %d), ignoring", len(key), MaxKeyLength)
 		return
@@ -103,7 +106,6 @@ func (c *OptimizedCache) Set(key string, value interface{}, expiration time.Dura
 	now := time.Now()
 	expTime := now.Add(expiration)
 
-	// Update existing item
 	if entry, exists := c.items[key]; exists {
 		oldSize := c.estimateEntrySize(entry)
 		entry.Value = value
@@ -114,7 +116,6 @@ func (c *OptimizedCache) Set(key string, value interface{}, expiration time.Dura
 		return
 	}
 
-	// Create new entry
 	entry := &OptimizedCacheEntry{
 		Value:     value,
 		ExpiresAt: expTime,
@@ -123,20 +124,21 @@ func (c *OptimizedCache) Set(key string, value interface{}, expiration time.Dura
 
 	entrySize := c.estimateEntrySize(entry)
 
-	// Check memory budget and evict if necessary
 	for (c.currentMemoryBytes+entrySize > c.maxMemoryBytes || len(c.items) >= c.maxSize) && len(c.items) > 0 {
 		if !c.evictOldest() {
-			break // No more items to evict
+			break
 		}
 	}
 
-	// Add new entry
 	c.items[key] = entry
 	c.currentMemoryBytes += entrySize
 	c.addToTail(entry)
 }
 
-// Get retrieves an item from the cache with memory-efficient access tracking
+// Get retrieves an item from the cache with memory-efficient access tracking.
+// It moves accessed items to the tail (most recently used position) and
+// automatically removes expired items when encountered.
+// Returns the value and true if found and valid, or nil and false otherwise.
 func (c *OptimizedCache) Get(key string) (interface{}, bool) {
 	c.mutex.Lock()
 	defer c.mutex.Unlock()
@@ -146,18 +148,17 @@ func (c *OptimizedCache) Get(key string) (interface{}, bool) {
 		return nil, false
 	}
 
-	// Check for expiration
 	if time.Now().After(entry.ExpiresAt) {
 		c.removeEntry(entry)
 		return nil, false
 	}
 
-	// Move to tail (most recently used)
 	c.moveToTail(entry)
 	return entry.Value, true
 }
 
-// Delete removes an item from the cache
+// Delete removes an item from the cache, freeing its memory and updating tracking.
+// This is a manual removal that updates both the hash map and LRU list.
 func (c *OptimizedCache) Delete(key string) {
 	c.mutex.Lock()
 	defer c.mutex.Unlock()
@@ -167,27 +168,26 @@ func (c *OptimizedCache) Delete(key string) {
 	}
 }
 
-// Cleanup removes expired items and performs memory optimization
+// Cleanup removes expired items and performs memory optimization.
+// It scans the LRU list for expired entries and enforces memory limits
+// by evicting least recently used items if necessary.
 func (c *OptimizedCache) Cleanup() {
 	c.mutex.Lock()
 	defer c.mutex.Unlock()
 
 	now := time.Now()
-	toRemove := make([]*OptimizedCacheEntry, 0, len(c.items)/10) // Pre-allocate for efficiency
+	toRemove := make([]*OptimizedCacheEntry, 0, len(c.items)/10)
 
-	// Collect expired entries (start from head - oldest items)
 	for entry := c.head.next; entry != c.tail; entry = entry.next {
 		if now.After(entry.ExpiresAt) {
 			toRemove = append(toRemove, entry)
 		}
 	}
 
-	// Remove expired entries
 	for _, entry := range toRemove {
 		c.removeEntry(entry)
 	}
 
-	// Perform memory pressure eviction if needed
 	for c.currentMemoryBytes > c.maxMemoryBytes && len(c.items) > 0 {
 		if !c.evictOldest() {
 			break
@@ -195,11 +195,12 @@ func (c *OptimizedCache) Cleanup() {
 	}
 }
 
-// evictOldest removes the least recently used item
-// Returns false if no items to evict
+// evictOldest removes the least recently used item from the cache.
+// Returns true if an item was evicted, false if the cache is empty.
+// Returns false if no items to evict.
 func (c *OptimizedCache) evictOldest() bool {
 	if c.head.next == c.tail {
-		return false // Empty cache
+		return false
 	}
 
 	oldest := c.head.next
@@ -207,25 +208,24 @@ func (c *OptimizedCache) evictOldest() bool {
 	return true
 }
 
-// removeEntry removes an entry from both the map and linked list
+// removeEntry removes an entry from both the map and linked list.
+// It updates memory tracking and clears references to prevent memory leaks.
+// Note: This function assumes the write lock is already held.
 func (c *OptimizedCache) removeEntry(entry *OptimizedCacheEntry) {
-	// Remove from map
 	delete(c.items, entry.Key)
 
-	// Update memory usage
 	c.currentMemoryBytes -= c.estimateEntrySize(entry)
 
-	// Remove from linked list
 	entry.prev.next = entry.next
 	entry.next.prev = entry.prev
 
-	// Clear references to help GC
 	entry.prev = nil
 	entry.next = nil
 	entry.Value = nil
 }
 
-// addToTail adds an entry to the tail (most recently used position)
+// addToTail adds an entry to the tail (most recently used position) of the LRU list.
+// This marks the entry as the most recently accessed item.
 func (c *OptimizedCache) addToTail(entry *OptimizedCacheEntry) {
 	entry.prev = c.tail.prev
 	entry.next = c.tail
@@ -233,24 +233,21 @@ func (c *OptimizedCache) addToTail(entry *OptimizedCacheEntry) {
 	c.tail.prev = entry
 }
 
-// moveToTail moves an existing entry to the tail (mark as most recently used)
+// moveToTail moves an existing entry to the tail (mark as most recently used).
+// This updates the LRU order when an item is accessed.
 func (c *OptimizedCache) moveToTail(entry *OptimizedCacheEntry) {
-	// Remove from current position
 	entry.prev.next = entry.next
 	entry.next.prev = entry.prev
 
-	// Add to tail
 	c.addToTail(entry)
 }
 
-// estimateEntrySize estimates the memory usage of a cache entry
-// Uses conservative estimates since unsafe.Sizeof is not allowed in Yaegi
+// estimateEntrySize calculates the approximate memory footprint of a cache entry.
+// Uses conservative estimates since unsafe.Sizeof is not allowed in Yaegi.
+// It accounts for the entry struct, key string, and value based on type.
 func (c *OptimizedCache) estimateEntrySize(entry *OptimizedCacheEntry) int64 {
-	// Conservative estimate for OptimizedCacheEntry struct overhead
-	// (3 pointers + time.Time + string) ≈ 80 bytes on 64-bit systems
 	size := int64(80) + int64(len(entry.Key))
 
-	// Estimate value size based on type
 	if entry.Value != nil {
 		switch v := entry.Value.(type) {
 		case string:
@@ -258,26 +255,23 @@ func (c *OptimizedCache) estimateEntrySize(entry *OptimizedCacheEntry) int64 {
 		case []byte:
 			size += int64(len(v))
 		case map[string]interface{}:
-			// Rough estimate for map overhead + keys + values
-			size += int64(len(v)) * 64 // 64 bytes per entry estimate
+			size += int64(len(v)) * 64
 			for key, val := range v {
 				size += int64(len(key))
-				// Estimate value size
 				switch val := val.(type) {
 				case string:
 					size += int64(len(val))
 				case []byte:
 					size += int64(len(val))
 				default:
-					size += 32 // Default estimate for other types
+					size += 32
 				}
 			}
 		case []string:
 			for _, s := range v {
-				size += int64(len(s)) + 16 // 16 bytes slice overhead per string
+				size += int64(len(s)) + 16
 			}
 		default:
-			// Generic estimate for unknown types
 			size += 64
 		}
 	}
@@ -285,7 +279,8 @@ func (c *OptimizedCache) estimateEntrySize(entry *OptimizedCacheEntry) int64 {
 	return size
 }
 
-// SetMaxSize changes the maximum number of items the cache can hold
+// SetMaxSize changes the maximum number of items the cache can hold.
+// If the new limit is smaller than current size, least recently used items are evicted.
 func (c *OptimizedCache) SetMaxSize(size int) {
 	if size <= 0 {
 		return
@@ -296,7 +291,6 @@ func (c *OptimizedCache) SetMaxSize(size int) {
 
 	c.maxSize = size
 
-	// Evict excess items if necessary
 	for len(c.items) > c.maxSize && len(c.items) > 0 {
 		if !c.evictOldest() {
 			break
@@ -304,7 +298,8 @@ func (c *OptimizedCache) SetMaxSize(size int) {
 	}
 }
 
-// SetMaxMemory sets the maximum memory budget in MB
+// SetMaxMemory sets the maximum memory budget in MB.
+// If current usage exceeds the new limit, least recently used items are evicted.
 func (c *OptimizedCache) SetMaxMemory(maxMemoryMB int) {
 	if maxMemoryMB <= 0 {
 		return
@@ -315,7 +310,6 @@ func (c *OptimizedCache) SetMaxMemory(maxMemoryMB int) {
 
 	c.maxMemoryBytes = int64(maxMemoryMB) * 1024 * 1024
 
-	// Evict items if over memory budget
 	for c.currentMemoryBytes > c.maxMemoryBytes && len(c.items) > 0 {
 		if !c.evictOldest() {
 			break
@@ -323,13 +317,15 @@ func (c *OptimizedCache) SetMaxMemory(maxMemoryMB int) {
 	}
 }
 
-// startAutoCleanup starts the background cleanup task
+// startAutoCleanup starts the background cleanup task for automatic maintenance.
+// The task runs periodically to remove expired entries and enforce memory limits.
 func (c *OptimizedCache) startAutoCleanup() {
 	c.cleanupTask = NewBackgroundTask("optimized-cache-cleanup", c.autoCleanupInterval, c.Cleanup, c.logger)
 	c.cleanupTask.Start()
 }
 
-// Close stops the automatic cleanup task
+// Close stops the automatic cleanup task and releases resources.
+// Should be called when the cache is no longer needed to prevent resource leaks.
 func (c *OptimizedCache) Close() {
 	if c.cleanupTask != nil {
 		c.cleanupTask.Stop()