22888612440

Committed 10 Mar 2026 05:30AM UTC coverage: 87.388% (+0.3%) from 87.113%

Build # 22888612440

Build Type

push

github

Committed by

orneryd

Commit Message

increasing test coverage

Run Details

3 of 3 new or added lines in 1 file covered. (100.0%)

15 existing lines in 4 files now uncovered.

87683 of 100338 relevant lines covered (87.39%)

1.01 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

98.64

/pkg/cache/query_cache.go

// Package cache provides query plan caching for NornicDB.
//
// Query plan caching avoids re-parsing identical Cypher queries,
// significantly improving throughput for repeated queries.
//
// Features:
// - LRU eviction for bounded memory
// - TTL expiration for stale plans
// - Thread-safe operations
// - Cache hit/miss statistics
//
// Usage:
//
//        cache := NewQueryCache(1000, 5*time.Minute)
//
//        // Check cache before parsing
//        if plan, ok := cache.Get(query); ok {
//                return plan // Cache hit
//        }
//
//        // Parse and cache
//        plan := parseQuery(query)
//        cache.Put(query, plan)
package cache

import (
        "container/list"
        "hash/fnv"
        "sync"
        "sync/atomic"
        "time"
)

// QueryCache is a thread-safe LRU cache for parsed query plans.
//
// The cache uses:
// - Hash map for O(1) lookups
// - Doubly-linked list for LRU ordering
// - TTL for automatic expiration
//
// Example:
//
//        cache := NewQueryCache(1000, 5*time.Minute)
//
//        // Try cache first
//        key := cache.Key(query, params)
//        if plan, ok := cache.Get(key); ok {
//                return plan.(*ParsedPlan)
//        }
//
//        // Parse and cache
//        plan := parseQuery(query)
//        cache.Put(key, plan)
type QueryCache struct {
        mu sync.RWMutex

        // Configuration
        maxSize int
        ttl     time.Duration
        enabled bool

        // LRU list and map
        list  *list.List
        items map[uint64]*list.Element

        // Statistics
        hits   uint64
        misses uint64
}

// cacheEntry holds a cached item with metadata.
type cacheEntry struct {
        key       uint64
        value     interface{}
        expiresAt time.Time
}

// NewQueryCache creates a new query cache.
//
// Parameters:
//   - maxSize: Maximum number of cached plans (LRU eviction when exceeded)
//   - ttl: Time-to-live for cached entries (0 = no expiration)
//
// Example:
//
//        // Cache up to 1000 plans for 5 minutes each
//        cache := NewQueryCache(1000, 5*time.Minute)
//
//        // Unlimited TTL (only LRU eviction)
//        cache = NewQueryCache(1000, 0)
func NewQueryCache(maxSize int, ttl time.Duration) *QueryCache {
        if maxSize <= 0 {
                maxSize = 1000
        }
        return &QueryCache{
                maxSize: maxSize,
                ttl:     ttl,
                enabled: true,
                list:    list.New(),
                items:   make(map[uint64]*list.Element, maxSize),
        }
}

// Key generates a cache key from query and parameters.
//
// The key is a 64-bit hash (FNV-1a algorithm) that uniquely identifies a query
// pattern. The hash includes the query text and parameter keys (but not values),
// allowing parameterized queries to be cached efficiently.
//
// Parameters:
//   - query: The Cypher query string
//   - params: Query parameters (only keys are hashed, not values)
//
// Returns:
//   - uint64 hash suitable for map lookups
//
// Example 1 - Basic Usage:
//
//        cache := cache.NewQueryCache(1000, 5*time.Minute)
//
//        query := "MATCH (n:Person {name: $name}) RETURN n"
//        params := map[string]interface{}{"name": "Alice"}
//
//        key := cache.Key(query, params)
//        fmt.Printf("Cache key: %d\n", key)
//
// Example 2 - Same Query, Different Values:
//
//        // These produce the SAME key (parameter values don't matter)
//        key1 := cache.Key("MATCH (n {id: $id}) RETURN n", map[string]interface{}{"id": 1})
//        key2 := cache.Key("MATCH (n {id: $id}) RETURN n", map[string]interface{}{"id": 2})
//        // key1 == key2 (same query pattern)
//
//        // This produces a DIFFERENT key (different query)
//        key3 := cache.Key("MATCH (n {name: $name}) RETURN n", map[string]interface{}{"name": "Bob"})
//        // key3 != key1 (different query pattern)
//
// Example 3 - Integration with Parser:
//
//        func executeQuery(query string, params map[string]interface{}) (*Result, error) {
//                cache := cache.GlobalQueryCache()
//                key := cache.Key(query, params)
//
//                // Try cache first
//                if plan, ok := cache.Get(key); ok {
//                        return executePlan(plan.(*ParsedPlan), params)
//                }
//
//                // Parse and cache
//                plan, err := parseQuery(query)
//                if err != nil {
//                        return nil, err
//                }
//                cache.Put(key, plan)
//
//                return executePlan(plan, params)
//        }
//
// Performance:
//   - FNV-1a hash: ~50-100 ns for typical queries
//   - O(1) lookup in cache map
//   - Parameter keys included for correctness
//   - Parameter values excluded for reusability
//
// ELI12:
//
// Think of the cache key like a fingerprint for a query:
//   - Same query pattern = same fingerprint
//   - Different values (like "Alice" vs "Bob") = same fingerprint
//   - Different query = different fingerprint
//
// Why? Because the query structure is what we cache, not the specific values.
// It's like caching a recipe (the steps) rather than the actual meal (with
// specific ingredients). You can use the same recipe with different ingredients!
func (c *QueryCache) Key(query string, params map[string]interface{}) uint64 {
        h := fnv.New64a()
        h.Write([]byte(query))

        // Include parameter keys (not values - they might differ)
        // This allows caching parameterized queries
        for k := range params {
                h.Write([]byte(k))
        }

        return h.Sum64()
}

// Get retrieves a cached plan if present and not expired.
//
// This method performs an O(1) lookup in the cache map and automatically:
//   - Checks TTL expiration (removes expired entries)
//   - Updates LRU ordering (moves accessed entry to front)
//   - Tracks hit/miss statistics
//
// Parameters:
//   - key: Cache key from Key() method
//
// Returns:
//   - (value, true) on cache hit
//   - (nil, false) on cache miss or expiration
//
// Example 1 - Basic Cache Check:
//
//        cache := cache.NewQueryCache(1000, 5*time.Minute)
//        key := cache.Key(query, params)
//
//        if plan, ok := cache.Get(key); ok {
//                fmt.Println("Cache hit!")
//                return plan.(*ParsedPlan)
//        }
//        fmt.Println("Cache miss - need to parse")
//
// Example 2 - Query Executor Pattern:
//
//        func (e *Executor) Execute(query string, params map[string]interface{}) (*Result, error) {
//                key := e.cache.Key(query, params)
//
//                // Fast path: cached plan
//                if cached, ok := e.cache.Get(key); ok {
//                        plan := cached.(*ParsedPlan)
//                        return e.executePlan(plan, params)
//                }
//
//                // Slow path: parse and cache
//                plan, err := e.parser.Parse(query)
//                if err != nil {
//                        return nil, err
//                }
//                e.cache.Put(key, plan)
//
//                return e.executePlan(plan, params)
//        }
//
// Example 3 - TTL Expiration:
//
//        cache := cache.NewQueryCache(1000, 1*time.Second)
//        key := cache.Key("MATCH (n) RETURN n", nil)
//
//        cache.Put(key, parsedPlan)
//
//        // Immediate access: cache hit
//        if _, ok := cache.Get(key); ok {
//                fmt.Println("Hit!") // Prints
//        }
//
//        // After TTL: cache miss (auto-removed)
//        time.Sleep(2 * time.Second)
//        if _, ok := cache.Get(key); !ok {
//                fmt.Println("Expired!") // Prints
//        }
//
// Example 4 - Type Assertion:
//
//        if cached, ok := cache.Get(key); ok {
//                // Type assert to your plan type
//                plan, ok := cached.(*ParsedPlan)
//                if !ok {
//                        return nil, fmt.Errorf("invalid cached type")
//                }
//                return executePlan(plan, params)
//        }
//
// Performance:
//   - Cache hit: O(1) map lookup + O(1) list move
//   - Cache miss: O(1) map lookup
//   - TTL check: O(1) time comparison
//   - Typical latency: <100 ns
//
// Thread Safety:
//   - Safe for concurrent reads (RLock)
//   - Safe for concurrent writes (Lock)
//   - Statistics updated atomically
//
// ELI12:
//
// Imagine a library with a "recently returned" shelf:
//   - Get checks if your book is on the shelf
//   - If found, you take it and move it to the front (most recent)
//   - If the book is too old (expired), it's thrown away
//   - If not found, you have to go find it in the main stacks (parse)
//
// The cache remembers what you looked at recently so you don't have to
// search the whole library every time!
func (c *QueryCache) Get(key uint64) (interface{}, bool) {
        if !c.enabled {
                atomic.AddUint64(&c.misses, 1)
                return nil, false
        }

        c.mu.RLock()
        elem, ok := c.items[key]
        c.mu.RUnlock()

        if !ok {
                atomic.AddUint64(&c.misses, 1)
                return nil, false
        }

        entry := elem.Value.(*cacheEntry)

        // Check TTL
        if c.ttl > 0 && time.Now().After(entry.expiresAt) {
                // Expired - remove and return miss
                c.mu.Lock()
                c.removeElement(elem)
                c.mu.Unlock()
                atomic.AddUint64(&c.misses, 1)
                return nil, false
        }

        // Move to front (most recently used)
        c.mu.Lock()
        c.list.MoveToFront(elem)
        c.mu.Unlock()

        atomic.AddUint64(&c.hits, 1)
        return entry.value, true
}

// Put adds a plan to the cache.
//
// This method stores a parsed query plan in the cache for future reuse.
// It automatically handles:
//   - LRU eviction when cache is full
//   - TTL timestamp setting
//   - Updating existing entries
//   - Moving entry to front of LRU list
//
// Parameters:
//   - key: Cache key from Key() method
//   - value: Parsed query plan (typically *ParsedPlan)
//
// Example 1 - Basic Caching:
//
//        cache := cache.NewQueryCache(1000, 5*time.Minute)
//
//        query := "MATCH (n:Person) RETURN n"
//        plan := parseQuery(query) // Your parser
//
//        key := cache.Key(query, nil)
//        cache.Put(key, plan)
//
//        // Later: instant retrieval
//        if cached, ok := cache.Get(key); ok {
//                fmt.Println("Reusing cached plan!")
//        }
//
// Example 2 - Parse-Once Pattern:
//
//        func getOrParsePlan(query string, params map[string]interface{}) (*ParsedPlan, error) {
//                cache := cache.GlobalQueryCache()
//                key := cache.Key(query, params)
//
//                // Try cache
//                if cached, ok := cache.Get(key); ok {
//                        return cached.(*ParsedPlan), nil
//                }
//
//                // Parse (expensive operation)
//                plan, err := parser.Parse(query)
//                if err != nil {
//                        return nil, err
//                }
//
//                // Cache for next time
//                cache.Put(key, plan)
//                return plan, nil
//        }
//
// Example 3 - Updating Cached Entry:
//
//        // First put
//        key := cache.Key(query, nil)
//        cache.Put(key, plan1)
//
//        // Later: update with optimized plan
//        optimizedPlan := optimizePlan(plan1)
//        cache.Put(key, optimizedPlan) // Replaces old value
//
// Example 4 - LRU Eviction:
//
//        cache := cache.NewQueryCache(3, 0) // Only 3 entries, no TTL
//
//        cache.Put(1, "plan-A")
//        cache.Put(2, "plan-B")
//        cache.Put(3, "plan-C")
//        // Cache: [C, B, A] (most recent first)
//
//        cache.Get(1) // Access A
//        // Cache: [A, C, B]
//
//        cache.Put(4, "plan-D") // Cache full, evicts B (least recent)
//        // Cache: [D, A, C]
//
// Performance:
//   - O(1) insertion or update
//   - O(1) eviction when full
//   - No allocations for updates
//   - Typical latency: <200 ns
//
// Memory Management:
//   - LRU eviction prevents unbounded growth
//   - TTL expiration removes stale entries
//   - Eviction happens synchronously on Put
//
// Thread Safety:
//   - Exclusive lock held during Put
//   - Safe for concurrent Put/Get operations
//
// ELI12:
//
// Think of Put like adding a book to the "recently returned" shelf:
//   - If there's space, just add it to the front
//   - If the shelf is full, remove the oldest book from the back
//   - If the book is already there, move it to the front with new info
//   - Mark when it was added so we know when it's too old
//
// The shelf always keeps the most recently used books, automatically
// throwing away old ones you haven't touched in a while!
func (c *QueryCache) Put(key uint64, value interface{}) {
        if !c.enabled {
                return
        }

        c.mu.Lock()
        defer c.mu.Unlock()

        // Check if already exists
        if elem, ok := c.items[key]; ok {
                // Update existing entry
                entry := elem.Value.(*cacheEntry)
                entry.value = value
                if c.ttl > 0 {
                        entry.expiresAt = time.Now().Add(c.ttl)
                }
                c.list.MoveToFront(elem)
                return
        }

        // Evict if at capacity
        for c.list.Len() >= c.maxSize {
                c.evictOldest()
        }

        // Add new entry
        entry := &cacheEntry{
                key:   key,
                value: value,
        }
        if c.ttl > 0 {
                entry.expiresAt = time.Now().Add(c.ttl)
        }

        elem := c.list.PushFront(entry)
        c.items[key] = elem
}

// Remove removes an entry from the cache.
//
// Use this to manually invalidate a cached query plan, for example when
// the underlying data schema changes or when you know a plan is no longer
// valid.
//
// Parameters:
//   - key: Cache key to remove
//
// Example 1 - Schema Change Invalidation:
//
//        func createIndex(label, property string) error {
//                if err := db.CreateIndex(label, property); err != nil {
//                        return err
//                }
//
//                // Invalidate affected queries
//                cache := cache.GlobalQueryCache()
//                for _, query := range affectedQueries {
//                        key := cache.Key(query, nil)
//                        cache.Remove(key)
//                }
//                return nil
//        }
//
// Example 2 - Selective Invalidation:
//
//        // Remove specific query from cache
//        query := "MATCH (n:Person) RETURN n"
//        key := cache.Key(query, nil)
//        cache.Remove(key)
//
//        // Next execution will re-parse
//        result := executeQuery(query, nil) // Cache miss
//
// Performance:
//   - O(1) removal from map and list
//   - No-op if key doesn't exist
func (c *QueryCache) Remove(key uint64) {
        c.mu.Lock()
        defer c.mu.Unlock()

        if elem, ok := c.items[key]; ok {
                c.removeElement(elem)
        }
}

// Clear removes all entries from the cache.
//
// Use this to completely reset the cache, for example during testing,
// after major schema changes, or when switching databases.
//
// Example 1 - Testing:
//
//        func TestQueryExecution(t *testing.T) {
//                cache := cache.NewQueryCache(100, 0)
//
//                // Test with cache
//                result1 := executeQuery("MATCH (n) RETURN n", nil)
//
//                // Clear for next test
//                cache.Clear()
//
//                // Test without cache
//                result2 := executeQuery("MATCH (n) RETURN n", nil)
//        }
//
// Example 2 - Schema Migration:
//
//        func migrateSchema() error {
//                // Perform migration
//                if err := db.Migrate(); err != nil {
//                        return err
//                }
//
//                // Invalidate all cached plans
//                cache.GlobalQueryCache().Clear()
//                return nil
//        }
//
// Example 3 - Memory Pressure:
//
//        // Free memory under pressure
//        if memoryPressure() {
//                cache.GlobalQueryCache().Clear()
//                runtime.GC()
//        }
//
// Performance:
//   - O(n) where n is cache size
//   - Reinitializes internal structures
//   - Resets statistics
func (c *QueryCache) Clear() {
        c.mu.Lock()
        defer c.mu.Unlock()

        c.list.Init()
        c.items = make(map[uint64]*list.Element, c.maxSize)
}

// Len returns the number of cached entries.
//
// Use this to monitor cache utilization or for debugging.
//
// Returns:
//   - Current number of entries in the cache
//
// Example 1 - Monitoring:
//
//        cache := cache.GlobalQueryCache()
//        fmt.Printf("Cache size: %d/%d\n", cache.Len(), 1000)
//
// Example 2 - Metrics:
//
//        func collectMetrics() {
//                cache := cache.GlobalQueryCache()
//                stats := cache.Stats()
//
//                metrics.Gauge("cache.size", float64(cache.Len()))
//                metrics.Gauge("cache.hit_rate", stats.HitRate)
//        }
//
// Performance:
//   - O(1) with read lock
func (c *QueryCache) Len() int {
        c.mu.RLock()
        defer c.mu.RUnlock()
        return c.list.Len()
}

// Stats returns cache statistics.
//
// Use this to monitor cache performance and tune cache size and TTL settings.
// Statistics are tracked atomically and have minimal performance overhead.
//
// Returns:
//   - CacheStats with hit rate, size, and access counts
//
// Example 1 - Performance Monitoring:
//
//        cache := cache.GlobalQueryCache()
//        stats := cache.Stats()
//
//        fmt.Printf("Cache Performance:\n")
//        fmt.Printf("  Size: %d/%d (%.1f%% full)\n",
//                stats.Size, stats.MaxSize,
//                float64(stats.Size)/float64(stats.MaxSize)*100)
//        fmt.Printf("  Hit Rate: %.2f%%\n", stats.HitRate)
//        fmt.Printf("  Hits: %d\n", stats.Hits)
//        fmt.Printf("  Misses: %d\n", stats.Misses)
//
// Example 2 - Metrics Collection:
//
//        func recordCacheMetrics() {
//                cache := cache.GlobalQueryCache()
//                stats := cache.Stats()
//
//                metrics.Gauge("query_cache.size", float64(stats.Size))
//                metrics.Gauge("query_cache.hit_rate", stats.HitRate)
//                metrics.Counter("query_cache.hits", float64(stats.Hits))
//                metrics.Counter("query_cache.misses", float64(stats.Misses))
//        }
//
// Example 3 - Tuning Decisions:
//
//        stats := cache.GlobalQueryCache().Stats()
//
//        if stats.HitRate < 50 {
//                log.Println("Low hit rate - consider increasing cache size")
//        }
//
//        if stats.Size == stats.MaxSize {
//                log.Println("Cache full - consider increasing maxSize")
//        }
//
// Example 4 - Periodic Reporting:
//
//        go func() {
//                ticker := time.NewTicker(1 * time.Minute)
//                for range ticker.C {
//                        stats := cache.GlobalQueryCache().Stats()
//                        log.Printf("Cache: %d entries, %.1f%% hit rate",
//                                stats.Size, stats.HitRate)
//                }
//        }()
//
// Interpreting Hit Rate:
//   - >80%: Excellent - cache is very effective
//   - 60-80%: Good - cache is helping
//   - 40-60%: Fair - consider tuning
//   - <40%: Poor - cache may be too small or TTL too short
//
// Performance:
//   - O(1) with read lock
//   - Atomic statistics access
//   - No allocations
//
// ELI12:
//
// Stats tells you how well your cache is working:
//   - Hit Rate: How often you find what you're looking for (higher is better)
//   - Size: How many things are in the cache right now
//   - Hits: How many times you found what you wanted
//   - Misses: How many times you had to go searching
//
// It's like checking your homework success rate - if you're getting most
// answers from your notes (high hit rate), your notes are working well!
func (c *QueryCache) Stats() CacheStats {
        hits := atomic.LoadUint64(&c.hits)
        misses := atomic.LoadUint64(&c.misses)

        c.mu.RLock()
        size := c.list.Len()
        c.mu.RUnlock()

        total := hits + misses
        var hitRate float64
        if total > 0 {
                hitRate = float64(hits) / float64(total) * 100
        }

        return CacheStats{
                Size:    size,
                MaxSize: c.maxSize,
                Hits:    hits,
                Misses:  misses,
                HitRate: hitRate,
        }
}

// CacheStats holds cache performance statistics.
//
// Use these statistics to monitor cache effectiveness and make tuning decisions.
// All fields are safe to read concurrently.
//
// Fields:
//   - Size: Current number of entries in the cache
//   - MaxSize: Maximum capacity (from NewQueryCache)
//   - Hits: Total number of successful cache lookups
//   - Misses: Total number of cache misses (parse required)
//   - HitRate: Percentage of lookups that were hits (0-100)
//
// Example 1 - Health Check:
//
//        func checkCacheHealth() error {
//                stats := cache.GlobalQueryCache().Stats()
//
//                if stats.HitRate < 50 {
//                        return fmt.Errorf("cache hit rate too low: %.1f%%", stats.HitRate)
//                }
//
//                if stats.Size == stats.MaxSize {
//                        log.Warn("Cache is full - consider increasing size")
//                }
//
//                return nil
//        }
//
// Example 2 - Dashboard Display:
//
//        stats := cache.GlobalQueryCache().Stats()
//        fmt.Printf(`
//        Query Cache Status:
//          Capacity: %d/%d (%.1f%% full)
//          Hit Rate: %.2f%%
//          Total Requests: %d
//            Hits: %d
//            Misses: %d
//        `,
//                stats.Size, stats.MaxSize,
//                float64(stats.Size)/float64(stats.MaxSize)*100,
//                stats.HitRate,
//                stats.Hits+stats.Misses,
//                stats.Hits,
//                stats.Misses)
//
// Example 3 - Prometheus Metrics:
//
//        func exportPrometheusMetrics(stats cache.CacheStats) {
//                prometheus.GaugeSet("query_cache_size", float64(stats.Size))
//                prometheus.GaugeSet("query_cache_max_size", float64(stats.MaxSize))
//                prometheus.GaugeSet("query_cache_hit_rate", stats.HitRate)
//                prometheus.CounterAdd("query_cache_hits_total", float64(stats.Hits))
//                prometheus.CounterAdd("query_cache_misses_total", float64(stats.Misses))
//        }
//
// ELI12:
//
// CacheStats is like a report card for your cache:
//   - Size/MaxSize: How full is your backpack? (5/10 books)
//   - Hits: How many times you found your homework in your backpack
//   - Misses: How many times you had to search your locker
//   - HitRate: Your success percentage (80% means you find it 8 out of 10 times)
//
// Higher hit rate = better cache = faster queries!
type CacheStats struct {
        Size    int     // Current number of entries
        MaxSize int     // Maximum capacity
        Hits    uint64  // Number of cache hits
        Misses  uint64  // Number of cache misses
        HitRate float64 // Hit rate percentage (0-100)
}

// SetEnabled enables or disables the cache.
//
// When disabled, all Get operations return cache misses and Put operations
// are no-ops. The cache is also cleared when disabled. Use this for debugging
// or when you want to bypass caching temporarily.
//
// Parameters:
//   - enabled: true to enable caching, false to disable
//
// Example 1 - Debugging:
//
//        // Disable cache to test parsing performance
//        cache := cache.GlobalQueryCache()
//        cache.SetEnabled(false)
//
//        start := time.Now()
//        for i := 0; i < 1000; i++ {
//                executeQuery("MATCH (n) RETURN n", nil)
//        }
//        fmt.Printf("Without cache: %v\n", time.Since(start))
//
//        // Re-enable for comparison
//        cache.SetEnabled(true)
//        start = time.Now()
//        for i := 0; i < 1000; i++ {
//                executeQuery("MATCH (n) RETURN n", nil)
//        }
//        fmt.Printf("With cache: %v\n", time.Since(start))
//
// Example 2 - Conditional Caching:
//
//        func executeQuery(query string, useCache bool) (*Result, error) {
//                cache := cache.GlobalQueryCache()
//                cache.SetEnabled(useCache)
//
//                // Execute query (cache behavior depends on useCache)
//                return executor.Execute(query, nil)
//        }
//
// Example 3 - Testing:
//
//        func TestParserWithoutCache(t *testing.T) {
//                cache := cache.NewQueryCache(100, 0)
//                cache.SetEnabled(false) // Force re-parsing
//
//                // All queries will be parsed fresh
//                for _, query := range testQueries {
//                        result := executeQuery(query, nil)
//                        // Verify parsing logic...
//                }
//        }
//
// Performance Impact:
//   - Disabled: All Get() returns false (cache miss)
//   - Disabled: All Put() are no-ops
//   - Disabling clears the cache (frees memory)
//
// Thread Safety:
//   - Safe to call concurrently
//   - Exclusive lock held during state change
func (c *QueryCache) SetEnabled(enabled bool) {
        c.mu.Lock()
        defer c.mu.Unlock()
        c.enabled = enabled

        if !enabled {
                c.list.Init()
                c.items = make(map[uint64]*list.Element, c.maxSize)
        }
}

// evictOldest removes the least recently used entry.
// Caller must hold the lock.
func (c *QueryCache) evictOldest() {
        elem := c.list.Back()
        if elem != nil {
                c.removeElement(elem)
        }
}

// removeElement removes an element from the cache.
// Caller must hold the lock.
func (c *QueryCache) removeElement(elem *list.Element) {
        c.list.Remove(elem)
        entry := elem.Value.(*cacheEntry)
        delete(c.items, entry.key)
}

// =============================================================================
// Global Query Cache (singleton for convenience)
// =============================================================================

var (
        globalQueryCache     *QueryCache
        globalQueryCacheOnce sync.Once
)

// GlobalQueryCache returns the global query cache instance.
//
// The global cache is a singleton that's lazily initialized with default
// settings (1000 entries, 5-minute TTL). Use ConfigureGlobalCache to
// customize the cache before first use.
//
// Returns:
//   - Shared QueryCache instance
//
// Example 1 - Simple Usage:
//
//        func executeQuery(query string, params map[string]interface{}) (*Result, error) {
//                cache := cache.GlobalQueryCache()
//                key := cache.Key(query, params)
//
//                if plan, ok := cache.Get(key); ok {
//                        return executePlan(plan.(*ParsedPlan), params)
//                }
//
//                plan, err := parseQuery(query)
//                if err != nil {
//                        return nil, err
//                }
//                cache.Put(key, plan)
//
//                return executePlan(plan, params)
//        }
//
// Example 2 - With Custom Configuration:
//
//        func init() {
//                // Configure before first use
//                cache.ConfigureGlobalCache(5000, 10*time.Minute)
//        }
//
//        func main() {
//                // Now uses custom configuration
//                cache := cache.GlobalQueryCache()
//                fmt.Printf("Cache size: %d\n", cache.Len())
//        }
//
// Example 3 - Monitoring:
//
//        go func() {
//                ticker := time.NewTicker(1 * time.Minute)
//                for range ticker.C {
//                        stats := cache.GlobalQueryCache().Stats()
//                        log.Printf("Cache hit rate: %.1f%%", stats.HitRate)
//                }
//        }()
//
// Default Configuration:
//   - MaxSize: 1000 entries
//   - TTL: 5 minutes
//   - Enabled: true
//
// Thread Safety:
//   - Singleton initialization is thread-safe
//   - All cache operations are thread-safe
//
// ELI12:
//
// GlobalQueryCache is like having ONE shared notebook for the whole class:
//   - Everyone uses the same notebook (singleton)
//   - First person to open it sets it up (lazy initialization)
//   - Everyone can read and write at the same time (thread-safe)
//   - No need to pass the notebook around - just call GlobalQueryCache()!
func GlobalQueryCache() *QueryCache {
        globalQueryCacheOnce.Do(func() {
                globalQueryCache = NewQueryCache(1000, 5*time.Minute)
        })
        return globalQueryCache
}

// ConfigureGlobalCache configures the global query cache.
//
// This function must be called before the first use of GlobalQueryCache()
// to customize the cache settings. Subsequent calls are no-ops (first call wins).
//
// Parameters:
//   - maxSize: Maximum number of cached plans (LRU eviction when exceeded)
//   - ttl: Time-to-live for cached entries (0 = no expiration)
//
// Example 1 - Application Initialization:
//
//        func main() {
//                // Configure cache early in main()
//                cache.ConfigureGlobalCache(5000, 10*time.Minute)
//
//                // Start application
//                server.Start()
//        }
//
// Example 2 - Environment-Based Configuration:
//
//        func init() {
//                maxSize := getEnvInt("CACHE_SIZE", 1000)
//                ttl := getEnvDuration("CACHE_TTL", 5*time.Minute)
//
//                cache.ConfigureGlobalCache(maxSize, ttl)
//        }
//
// Example 3 - Production vs Development:
//
//        func init() {
//                if os.Getenv("ENV") == "production" {
//                        // Large cache for production
//                        cache.ConfigureGlobalCache(10000, 15*time.Minute)
//                } else {
//                        // Small cache for development
//                        cache.ConfigureGlobalCache(100, 1*time.Minute)
//                }
//        }
//
// Example 4 - Testing:
//
//        func TestMain(m *testing.M) {
//                // Small cache for tests
//                cache.ConfigureGlobalCache(10, 0)
//                os.Exit(m.Run())
//        }
//
// Timing:
//   - Call in init() or early in main()
//   - Before any query execution
//   - Before starting HTTP server
//
// Thread Safety:
//   - First call wins (sync.Once)
//   - Subsequent calls are ignored
//   - Safe to call from multiple goroutines
//
// ELI12:
//
// ConfigureGlobalCache is like setting up the classroom before students arrive:
//   - You decide how big the shared notebook should be (maxSize)
//   - You decide how long notes stay valid (ttl)
//   - Once students arrive, you can't change the notebook (first call wins)
//   - Do this in init() or main() before anyone uses the cache!
func ConfigureGlobalCache(maxSize int, ttl time.Duration) {
        globalQueryCacheOnce.Do(func() {
                globalQueryCache = NewQueryCache(maxSize, ttl)
        })
}

orneryd / NornicDB / 22888612440

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous