cache

Documentation

Overview

Package cache provides a lock-free adaptive in-memory cache implementation. CloxCache uses protected-freq eviction: items with high frequency are protected, with LRU as a tiebreaker among same-frequency items.

Index

• func ComputeShardConfig(cacheSize uint64) (numShards, slotsPerShard int)
• func FormatMemory(bytes uint64) string
• type AdaptiveStats
• type CloxCache
  • func NewCloxCache[K Key, V any](cfg Config) *CloxCache[K, V]
  • func (c *CloxCache[K, V]) AverageK() float64
  • func (c *CloxCache[K, V]) Close()
  • func (c *CloxCache[K, V]) Get(key K) (V, bool)
  • func (c *CloxCache[K, V]) GetAdaptiveStats() []AdaptiveStats
  • 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 AdaptiveStats

type AdaptiveStats struct {
	ShardID            int
	K                  uint32  // current protection threshold for this shard
	GraduationRate     float64 // fraction of items whose freq crossed the shard's k
	EvictedUnprotected uint64  // items evicted with freq <= k
	EvictedProtected   uint64  // items evicted with freq > k (fallback)
	ReachedProtected   uint64  // items whose freq crossed the shard's current k
}

AdaptiveStats returns per-shard adaptive threshold statistics

type CloxCache

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

CloxCache is a lock-free adaptive in-memory cache. 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]) AverageK

func (c *CloxCache[K, V]) AverageK() float64

AverageK returns the average protection threshold across all shards

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]) GetAdaptiveStats

func (c *CloxCache[K, V]) GetAdaptiveStats() []AdaptiveStats

GetAdaptiveStats returns adaptive threshold stats for all shards

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 return 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
	// (recommend: 15 for temporal workloads and low latency)
	SweepPercent int // Percentage of shard to scan during eviction
}

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)