import "github.com/samber/hot" cache := hot.NewHotCache[string, int](hot.LRU, 1_000_000). WithTTL(10*time.Minute). Build() cache.Set("hello", 42) values, missing := cache.GetMany([]string{"bar", "baz", "hello"}) // values: {"hello": 42} // missing: ["baz", "bar"]

// Set default time-to-live for all cache entries WithTTL(ttl time.Duration) // Add random jitter to TTL to prevent cache stampedes WithJitter(lambda float64, upperBound time.Duration) // Enable background cleanup of expired items WithJanitor()

// Keep serving stale data while refreshing in background WithRevalidation(stale time.Duration, loaders ...hot.Loader[K, V]) // Control behavior when revalidation fails (KeepOnError/DropOnError) WithRevalidationErrorPolicy(policy hot.RevalidationErrorPolicy)

// Use separate cache for missing keys (prevents main cache pollution) WithMissingCache(algorithm hot.EvictionAlgorithm, capacity int) // Share missing key cache with main cache (good for low missing rate) WithMissingSharedCache()

// Set chain of loaders for cache misses (primary, fallback, etc.) WithLoaders(loaders ...hot.Loader[K, V])

// Disable mutex for single-threaded applications (performance boost) WithoutLocking() // Copy values when reading (prevents external modification) WithCopyOnRead(copier func(V) V) // Copy values when writing (ensures cache owns the data) WithCopyOnWrite(copier func(V) V)

// Split cache into multiple shards to reduce lock contention WithSharding(shards uint64, hasher sharded.Hasher[K])

// Called when items are evicted (LRU/LFU/TinyLFU/W-TinyLFU/S3FIFO/expiration) WithEvictionCallback(callback func(key K, value V)) // Preload cache on startup with data from loader WithWarmUp(loader func() (map[K]V, []K, error)) // Preload with timeout protection for slow data sources WithWarmUpWithTimeout(timeout time.Duration, loader func() (map[K]V, []K, error))

// Enable Prometheus metrics collection with the specified cache name WithPrometheusMetrics(cacheName string)

hot.LRU hot.LFU hot.TinyLFU hot.WTinyLFU hot.S3FIFO hot.TwoQueue hot.ARC hot.FIFO

hot.KeepOnError hot.DropOnError

// Store a key-value pair in the cache cache.Set(key K, value V) // Store with custom time-to-live (overrides default TTL) cache.SetWithTTL(key K, value V, ttl time.Duration) // Retrieve value by key, returns found status and any error cache.Get(key K) -> (value V, found bool, error error) // Check if key exists in cache (no side effects) cache.Has(key K) -> bool // Remove key from cache, returns true if key existed cache.Delete(key K) -> bool

// Store multiple key-value pairs atomically cache.SetMany(items map[K]V) // Retrieve multiple values, returns found items and missing keys cache.GetMany(keys []K) -> (found map[K]V, missing []K) // Check existence of multiple keys, returns map of key->exists cache.HasMany(keys []K) -> map[K]bool // Remove multiple keys, returns map of key->was_deleted cache.DeleteMany(keys []K) -> map[K]bool

// Get value without updating access time or LRU position cache.Peek(key K) -> (value V, found bool) // Get multiple values without side effects cache.PeekMany(keys []K) -> (found map[K]V, missing []K) // Get all keys in cache (order not guaranteed) cache.Keys() -> []K // Get all values in cache (order not guaranteed) cache.Values() -> []V // Get all keys and values in cache (order not guaranteed) cache.All() -> map[K]V // Iterate over all key-value pairs, return false to stop cache.Range(fn func(key K, value V) bool) // Get current number of items in cache cache.Len() -> int // Get (current_size, max_capacity) of cache cache.Capacity() -> (current int, max int) // Get (algorithm_name, algorithm_version) info cache.Algorithm() -> (name string, version string)

// Remove all items from cache immediately cache.Purge() // Preload cache with data from loader function cache.WarmUp(loader hot.Loader[K, V]) -> error // Start background cleanup of expired items cache.Janitor() // Stop background janitor process cache.StopJanitor()

// Loader function signature for fetching data from external sources // Called when cache misses occur, with automatic deduplication of concurrent requests type Loader[K comparable, V any] func(keys []K) (found map[K]V, err error) // Example: func userLoader(keys []string) (found map[string]*User, err error) { // Fetch users from database // Return map of found users (key -> user object) // Return empty map if no users found (not an error) // Return error if database query fails return users, nil }

// Hasher is responsible for generating unsigned, 16 bit hash of provided key. // Hasher should minimize collisions. For great performance, a fast function is preferable. type Hasher[K any] func(key K) uint64 // Example: func hash(key string) uint64 { hasher := fnv.New64a() hasher.Write([]byte(s)) return hasher.Sum64() }

cache := lru.NewLRUCache[string, *User](100_000)

import ( "github.com/samber/hot/pkg/lfu" "github.com/samber/hot/pkg/safe" ) cache := safe.NewSafeInMemoryCache( lru.NewLRUCache[string, *User](100_000), )

import ( "hash/fnv" "github.com/samber/hot/pkg/lfu" "github.com/samber/hot/pkg/safe" "github.com/samber/hot/pkg/sharded" ) cache := sharded.NewShardedInMemoryCache( 100, // Number of shards func() base.InMemoryCache[K, *item[V]] { // Cache builder for each shard return safe.NewSafeInMemoryCache( lru.NewLRUCache[string, *User](100_000), ) }, func(key string) uint64 { // Hash function h := fnv.New64a() h.Write([]byte(key)) return h.Sum64() }, )

import "github.com/samber/hot" cache := hot.NewHotCache[string, int](hot.LRU, 100_000). WithMissingSharedCache(). Build()

import "github.com/samber/hot" cache := hot.NewHotCache[string, int](hot.LRU, 100_000). WithMissingCache(hot.LFU, 50_000). Build()

import "github.com/samber/hot" // Available eviction policies: hot.LRU, hot.LFU, hot.TinyLFU, hot.WTinyLFU, hot.S3FIFO, hot.TwoQueue, hot.ARC, hot.FIFO // Capacity: 100k keys/values cache := hot.NewHotCache[string, int](hot.LRU, 100_000). Build() cache.Set("hello", 42) cache.SetMany(map[string]int{"foo": 1, "bar": 2}) values, missing := cache.GetMany([]string{"bar", "baz", "hello"}) // values: {"bar": 2, "hello": 42} // missing: ["baz"] value, found, _ := cache.Get("foo") // value: 1 // found: true

// Handle cache operations with proper error checking value, found, err := cache.Get("key") if err != nil { // Handle loader errors (database connection, network issues, etc.) log.Printf("Cache get error: %v", err) return } if !found { // Key doesn't exist in cache and wasn't found by loaders log.Printf("Key not found: %s", "key") return } // Use value safely fmt.Printf("Value: %v", value) // Batch operations with error handling values, missing := cache.GetMany([]string{"key1", "key2", "key3"}) if len(missing) > 0 { log.Printf("Missing keys: %v", missing) } // Process found values for key, value := range values { fmt.Printf("%s: %v", key, value) }

import "github.com/samber/hot" cache := hot.NewHotCache[string, *User](hot.LRU, 100_000). WithLoaders(func(keys []string) (found map[string]*User, err error) { rows, err := db.Query("SELECT * FROM users WHERE id IN (?)", keys) // ... return users, err }). Build() user, found, err := cache.Get("user-123") // might fail if "user-123" is not in cache and loader returns error // get or create user, found, err := cache.GetWithLoaders( "user-123", func(keys []string) (found map[string]*User, err error) { rows, err := db.Query("SELECT * FROM users WHERE id IN (?)", keys) // ... return users, err }, func(keys []string) (found map[string]*User, err error) { rows, err := db.Query("INSERT INTO users (id, email) VALUES (?, ?)", id, email) // ... return users, err }, ) // either `err` is not nil, or `found` is true // missing value vs nil value user, found, err := cache.GetWithLoaders( "user-123", func(keys []string) (found map[string]*User, err error) { // value could not be found return map[string]*User{}, nil // or // value exists but is nil return map[string]*User{"user-123": nil}, nil }, )

import "github.com/samber/hot" cache := hot.NewHotCache[string, int](hot.LRU, 100_000). WithTTL(1 * time.Minute). // items will expire after 1 minute WithJitter(2, 30*time.Second). // optional: randomizes the TTL with an exponential distribution in the range [0, +30s) WithJanitor(1 * time.Minute). // optional: background job will purge expired keys every minutes Build() cache.SetWithTTL("foo", 42, 10*time.Second) // shorter TTL for "foo" key

loader := func(keys []string) (found map[string]*User, err error) { rows, err := db.Query("SELECT * FROM users WHERE id IN (?)", keys) // ... return users, err } cache := hot.NewHotCache[string, *User](hot.LRU, 100_000). WithTTL(1 * time.Minute). // Keep delivering cache 5 more second, but refresh value in background. // Keys that are not fetched during the interval will be dropped anyway. // A timeout or error in loader will drop keys. WithRevalidation(5 * time.Second, loader). // On revalidation error, the cache entries are either kept or dropped. // Optional (default: drop) WithRevalidationErrorPolicy(hot.KeepOnError). Build()

import ( "github.com/prometheus/client_golang/prometheus" "github.com/prometheus/client_golang/prometheus/promhttp" "github.com/samber/hot" "net/http" ) // Create cache with Prometheus metrics cache := hot.NewHotCache[string, string](hot.LRU, 1000). WithTTL(5*time.Minute). WithJitter(0.5, 10*time.Second). WithRevalidation(10*time.Second). WithRevalidationErrorPolicy(hot.KeepOnError). WithPrometheusMetrics("users-by-id"). WithMissingCache(hot.ARC, 1000). Build() // Register the cache metrics with Prometheus err := prometheus.Register(cache) if err != nil { log.Fatalf("Failed to register metrics: %v", err) } defer prometheus.Unregister(cache) // Set up HTTP server to expose metrics http.Handle("/metrics", promhttp.Handler()) http.ListenAndServe(":8080", nil)