cache

Documentation

Overview

Package cache provides a lock-free adaptive in-memory LRU cache implementation. CloxCache combines CLOCK-Pro eviction with TinyLFU admission and adaptive frequency decay.

Index

• func ComputeShardConfig(cacheSize uint64) (numShards, slotsPerShard int)
• func FormatMemory(bytes uint64) string
• type CloxCache
  • func NewCloxCache[K Key, V any](cfg Config) *CloxCache[K, V]
  • func (c *CloxCache[K, V]) Close()
  • func (c *CloxCache[K, V]) Get(key K) (V, bool)
  • func (c *CloxCache[K, V]) Put(key K, value V) bool
  • func (c *CloxCache[K, V]) Stats() (hits, misses, evictions uint64)
• type Config
  • func ConfigFromHardware() Config
  • func ConfigFromMemorySize(targetBytes uint64) Config
  • func (c Config) EstimateMemoryUsage() uint64
• type HardwareConfig
  • func DetectHardware() HardwareConfig
• type Key

Functions

func ComputeShardConfig

func ComputeShardConfig(cacheSize uint64) (numShards, slotsPerShard int)

ComputeShardConfig calculates optimal shard configuration for a target cache size

func FormatMemory

func FormatMemory(bytes uint64) string

FormatMemory formats bytes as human-readable string

Types

type CloxCache

type CloxCache[K Key, V any] struct {
	// contains filtered or unexported fields
}

CloxCache is a lock-free adaptive in-memory cache with CLOCK-Pro eviction. It stores generic keys of type K (string or []byte) and values of type V.

func NewCloxCache

func NewCloxCache[K Key, V any](cfg Config) *CloxCache[K, V]

NewCloxCache creates a new cache with the given configuration

func (*CloxCache[K, V]) Close

func (c *CloxCache[K, V]) Close()

Close stops background goroutines and waits for them to exit. Safe to call multiple times.

func (*CloxCache[K, V]) Get

func (c *CloxCache[K, V]) Get(key K) (V, bool)

Get retrieves a value from the cache (lock-free)

func (*CloxCache[K, V]) Put

func (c *CloxCache[K, V]) Put(key K, value V) bool

Put inserts or updates a value in the cache

func (*CloxCache[K, V]) Stats

func (c *CloxCache[K, V]) Stats() (hits, misses, evictions uint64)

Stats returns cache statistics

type Config

type Config struct {
	NumShards     int  // Must be power of 2
	SlotsPerShard int  // Must be power of 2
	Capacity      int  // Max entries (0 = use SlotsPerShard * NumShards as default)
	CollectStats  bool // Enable hit/miss/eviction counters (default: false for performance)
	AdaptiveDecay bool // Enable adaptive decay tuning (implies CollectStats)
}

Config holds CloxCache configuration

func ConfigFromHardware

func ConfigFromHardware() Config

ConfigFromHardware creates a CloxCache config from detected hardware

func ConfigFromMemorySize

func ConfigFromMemorySize(targetBytes uint64) Config

ConfigFromMemorySize creates a CloxCache config for a specific memory target

func (Config) EstimateMemoryUsage

func (c Config) EstimateMemoryUsage() uint64

EstimateMemoryUsage estimates total memory usage for a given configuration

type HardwareConfig

type HardwareConfig struct {
	NumCPU        int    // Number of logical CPUs
	TotalMemory   uint64 // Total system memory in bytes
	CacheSize     uint64 // Recommended cache size in bytes
	NumShards     int    // Recommended number of shards
	SlotsPerShard int    // Recommended slots per shard
}

HardwareConfig contains detected hardware specifications

func DetectHardware

func DetectHardware() HardwareConfig

DetectHardware detects system hardware and returns recommended configuration

type Key

type Key interface {
	~string | ~[]byte
}

Key is a type constraint for cache keys (string or []byte)