cache

package
v0.0.0-...-8acab51 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 26, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package cache provides caching implementations using ecache.

Package cache provides multi-level caching with LRU and LFU eviction policies.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrKeyNotFound = errors.New("key not found")
	ErrCacheFull   = errors.New("cache is full")
	ErrKeyExpired  = errors.New("key has expired")
)

Common errors

Functions

This section is empty.

Types

type Cache 

type Cache interface {
	// Get retrieves a value from the cache.
	Get(ctx context.Context, key string) (interface{}, error)

	// Set stores a value in the cache with optional TTL.
	Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error

	// Delete removes a key from the cache.
	Delete(ctx context.Context, key string) error

	// Exists checks if a key exists in the cache.
	Exists(ctx context.Context, key string) bool

	// Clear removes all entries from the cache.
	Clear(ctx context.Context) error

	// Stats returns cache statistics.
	Stats() CacheStats

	// Close closes the cache and releases resources.
	Close() error
}

Cache is the interface for cache implementations.

type CacheManager 

type CacheManager struct {
	// contains filtered or unexported fields
}

CacheManager manages named cache instances.

func NewCacheManager 

func NewCacheManager() *CacheManager

NewCacheManager creates a new cache manager.

func (*CacheManager) ClearAll 

func (m *CacheManager) ClearAll(ctx context.Context)

func (*CacheManager) Close 

func (m *CacheManager) Close()

func (*CacheManager) Get 

func (m *CacheManager) Get(name string) (Cache, bool)

func (*CacheManager) Register 

func (m *CacheManager) Register(name string, c Cache)

func (*CacheManager) Stats 

func (m *CacheManager) Stats() map[string]CacheStats

func (*CacheManager) Unregister 

func (m *CacheManager) Unregister(name string)

type CacheStats 

type CacheStats struct {
	Hits       int64   `json:"hits"`
	Misses     int64   `json:"misses"`
	Sets       int64   `json:"sets"`
	Deletes    int64   `json:"deletes"`
	Evictions  int64   `json:"evictions"`
	Size       int64   `json:"size"`
	Capacity   int64   `json:"capacity"`
	HitRate    float64 `json:"hit_rate"`
	MemoryUsed int64   `json:"memory_used,omitempty"`
}

CacheStats holds cache statistics.

type Config 

type Config struct {
	// MaxSize is the maximum number of entries.
	MaxSize int `yaml:"max_size"`
	// MaxMemory is the maximum memory usage in bytes (0 = unlimited).
	MaxMemory int64 `yaml:"max_memory"`
	// DefaultTTL is the default TTL for entries (0 = no expiration).
	DefaultTTL time.Duration `yaml:"default_ttl"`
	// EvictionPolicy is the eviction policy to use.
	EvictionPolicy EvictionPolicy `yaml:"eviction_policy"`
	// CleanupInterval is the interval for cleaning up expired entries.
	CleanupInterval time.Duration `yaml:"cleanup_interval"`
	// OnEvict is called when an entry is evicted.
	OnEvict func(key string, value interface{})
}

Config holds cache configuration.

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns the default cache configuration.

type DiskCache 

type DiskCache struct {
	// contains filtered or unexported fields
}

DiskCache implements a disk-based cache.

func NewDiskCache 

func NewDiskCache(config L2Config) (*DiskCache, error)

NewDiskCache creates a new disk cache.

func (*DiskCache) Clear 

func (c *DiskCache) Clear(ctx context.Context) error

Clear removes all entries from the cache.

func (*DiskCache) Close 

func (c *DiskCache) Close() error

Close closes the cache.

func (*DiskCache) Delete 

func (c *DiskCache) Delete(ctx context.Context, key string) error

Delete removes a key from the cache.

func (*DiskCache) DiskSize 

func (c *DiskCache) DiskSize() int64

DiskSize returns the current disk usage.

func (*DiskCache) Exists 

func (c *DiskCache) Exists(ctx context.Context, key string) bool

Exists checks if a key exists in the cache.

func (*DiskCache) Get 

func (c *DiskCache) Get(ctx context.Context, key string) (interface{}, error)

Get retrieves a value from the cache.

func (*DiskCache) Len 

func (c *DiskCache) Len() int

Len returns the number of items in the cache.

func (*DiskCache) Set 

func (c *DiskCache) Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error

Set stores a value in the cache.

func (*DiskCache) Stats 

func (c *DiskCache) Stats() CacheStats

Stats returns cache statistics.

type ECache 

type ECache struct {
	// contains filtered or unexported fields
}

ECache wraps ecache.Cache with the Cache interface.

func NewECache 

func NewECache(config Config) *ECache

NewECache creates a new ecache-based cache. bucketCount: number of buckets (shards) for concurrent access bucketSize: maximum items per bucket

func (*ECache) Clear 

func (c *ECache) Clear(ctx context.Context) error

Clear removes all entries from the cache.

func (*ECache) Close 

func (c *ECache) Close() error

Close closes the cache and releases resources.

func (*ECache) Delete 

func (c *ECache) Delete(ctx context.Context, key string) error

Delete removes a key from the cache.

func (*ECache) Exists 

func (c *ECache) Exists(ctx context.Context, key string) bool

Exists checks if a key exists in the cache.

func (*ECache) Get 

func (c *ECache) Get(ctx context.Context, key string) (interface{}, error)

Get retrieves a value from the cache.

func (*ECache) GetOrSet 

func (c *ECache) GetOrSet(ctx context.Context, key string, fn func() (interface{}, error)) (interface{}, error)

GetOrSet retrieves a value or sets it if not present.

func (*ECache) Len 

func (c *ECache) Len() int

Len returns the number of items in the cache.

func (*ECache) Set 

func (c *ECache) Set(ctx context.Context, key string, value interface{}) error

Set stores a value in the cache. TTL is determined by the DefaultTTL in config at cache creation time.

func (*ECache) SetNX 

func (c *ECache) SetNX(ctx context.Context, key string, value interface{}) bool

SetNX sets a value only if the key doesn't exist.

func (*ECache) Stats 

func (c *ECache) Stats() CacheStats

Stats returns cache statistics.

func (*ECache) Touch 

func (c *ECache) Touch(ctx context.Context, key string) bool

Touch updates the access time of a key.

type ECache2 

type ECache2 struct {
	// contains filtered or unexported fields
}

ECache2 wraps ecache.Cache with LRU-2 mode for better hot data protection.

func NewECache2 

func NewECache2(config Config) *ECache2

NewECache2 creates a new ecache-based cache with LRU-2 mode. LRU-2 mode protects frequently accessed data from being evicted by bulk operations.

func (*ECache2) Clear 

func (c *ECache2) Clear(ctx context.Context) error

Clear removes all entries from the cache.

func (*ECache2) Close 

func (c *ECache2) Close() error

Close closes the cache and releases resources.

func (*ECache2) Delete 

func (c *ECache2) Delete(ctx context.Context, key string) error

Delete removes a key from the cache.

func (*ECache2) Exists 

func (c *ECache2) Exists(ctx context.Context, key string) bool

Exists checks if a key exists in the cache.

func (*ECache2) Get 

func (c *ECache2) Get(ctx context.Context, key string) (interface{}, error)

Get retrieves a value from the cache.

func (*ECache2) Set 

func (c *ECache2) Set(ctx context.Context, key string, value interface{}) error

Set stores a value in the cache. TTL is determined by the DefaultTTL in config at cache creation time.

func (*ECache2) Stats 

func (c *ECache2) Stats() CacheStats

Stats returns cache statistics.

type Entry 

type Entry struct {
	Key         string
	Value       interface{}
	Size        int64
	CreatedAt   int64 // unix nanos
	ExpiresAt   int64 // unix nanos, 0 = no expiration
	AccessedAt  int64 // unix nanos
	AccessCount int64
}

Entry represents a cache entry.

func (*Entry) IsExpired 

func (e *Entry) IsExpired() bool

IsExpired checks if the entry has expired.

func (*Entry) TTL 

func (e *Entry) TTL() time.Duration

TTL returns the remaining time to live.

type EvictionPolicy 

type EvictionPolicy string

EvictionPolicy defines the cache eviction policy. 

const (
	// LRU evicts the least recently used entries.
	LRU EvictionPolicy = "lru"
	// LFU evicts the least frequently used entries.
	LFU EvictionPolicy = "lfu"
	// FIFO evicts the oldest entries first.
	FIFO EvictionPolicy = "fifo"
)

type GenericCache 

type GenericCache[K genericCacheKey] struct {
	// contains filtered or unexported fields
}

GenericCache is a lightweight generic cache with type-safe keys. K can be string, int, int64, uint64, etc.

func NewGenericCache 

func NewGenericCache[K genericCacheKey](config Config) *GenericCache[K]

NewGenericCache creates a new generic cache.

func NewGenericCacheWithStats 

func NewGenericCacheWithStats(config Config, poolName string) *GenericCache[string]

NewGenericCacheWithStats creates a new generic cache with local stats tracking.

func (*GenericCache[K]) Del 

func (c *GenericCache[K]) Del(key K)

Del removes a key from the cache.

func (*GenericCache[K]) Get 

func (c *GenericCache[K]) Get(key K) (interface{}, bool)

Get retrieves a value from the cache.

func (*GenericCache[K]) GetInt64 

func (c *GenericCache[K]) GetInt64(key K) (int64, bool)

GetInt64 retrieves an int64 value from the cache.

func (*GenericCache[K]) Put 

func (c *GenericCache[K]) Put(key K, value interface{})

Put stores a value in the cache.

func (*GenericCache[K]) PutInt64 

func (c *GenericCache[K]) PutInt64(key K, value int64)

PutInt64 stores an int64 value in the cache.

func (*GenericCache[K]) Stats 

func (c *GenericCache[K]) Stats() CacheStats

Stats returns local cache statistics.

type L1Config 

type L1Config struct {
	Config
	// ShardCount is the number of shards for concurrent access.
	ShardCount int `yaml:"shard_count"`
}

L1Config holds L1 (memory) cache configuration.

func DefaultL1Config 

func DefaultL1Config() L1Config

DefaultL1Config returns the default L1 cache configuration.

type L2Config 

type L2Config struct {
	Config
	// Path is the directory path for disk cache.
	Path string `yaml:"path"`
	// MaxDiskSize is the maximum disk usage in bytes.
	MaxDiskSize int64 `yaml:"max_disk_size"`
	// Compression enables compression for stored values.
	Compression bool `yaml:"compression"`
	// CompressionLevel is the compression level (1-9).
	CompressionLevel int `yaml:"compression_level"`
}

L2Config holds L2 (disk) cache configuration.

func DefaultL2Config 

func DefaultL2Config() L2Config

DefaultL2Config returns the default L2 cache configuration.

type LFUCache 

type LFUCache struct {
	// contains filtered or unexported fields
}

LFUCache implements Cache with least-frequently-used eviction.

func NewLFUCache 

func NewLFUCache(config Config) *LFUCache

NewLFUCache creates a new LFU cache.

func (*LFUCache) Clear 

func (c *LFUCache) Clear(ctx context.Context) error

func (*LFUCache) Close 

func (c *LFUCache) Close() error

func (*LFUCache) Delete 

func (c *LFUCache) Delete(ctx context.Context, key string) error

func (*LFUCache) Exists 

func (c *LFUCache) Exists(ctx context.Context, key string) bool

func (*LFUCache) Get 

func (c *LFUCache) Get(ctx context.Context, key string) (interface{}, error)

func (*LFUCache) GetFrequency 

func (c *LFUCache) GetFrequency(key string) (int64, bool)

GetFrequency returns the access frequency for a key.

func (*LFUCache) Len 

func (c *LFUCache) Len() int

func (*LFUCache) Set 

func (c *LFUCache) Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error

func (*LFUCache) Stats 

func (c *LFUCache) Stats() CacheStats

type LRUCache 

type LRUCache struct {
	// contains filtered or unexported fields
}

LRUCache implements Cache with least-recently-used eviction.

func NewLRUCache 

func NewLRUCache(config Config) *LRUCache

NewLRUCache creates a new LRU cache.

func (*LRUCache) Clear 

func (c *LRUCache) Clear(ctx context.Context) error

func (*LRUCache) Close 

func (c *LRUCache) Close() error

func (*LRUCache) Delete 

func (c *LRUCache) Delete(ctx context.Context, key string) error

func (*LRUCache) Exists 

func (c *LRUCache) Exists(ctx context.Context, key string) bool

func (*LRUCache) Get 

func (c *LRUCache) Get(ctx context.Context, key string) (interface{}, error)

func (*LRUCache) GetOrSet 

func (c *LRUCache) GetOrSet(ctx context.Context, key string, fn func() (interface{}, error), ttl time.Duration) (interface{}, error)

func (*LRUCache) Keys 

func (c *LRUCache) Keys() []string

func (*LRUCache) Len 

func (c *LRUCache) Len() int

func (*LRUCache) Set 

func (c *LRUCache) Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error

func (*LRUCache) SetNX 

func (c *LRUCache) SetNX(ctx context.Context, key string, value interface{}, ttl time.Duration) (bool, error)

func (*LRUCache) Stats 

func (c *LRUCache) Stats() CacheStats

func (*LRUCache) Touch 

func (c *LRUCache) Touch(ctx context.Context, key string) bool

type MultiLevelCache 

type MultiLevelCache struct {
	// contains filtered or unexported fields
}

MultiLevelCache combines L1 (memory) and L2 (disk) caches.

func NewMultiLevelCache 

func NewMultiLevelCache(config MultiLevelConfig) (*MultiLevelCache, error)

NewMultiLevelCache creates a new multi-level cache.

func (*MultiLevelCache) Clear 

func (c *MultiLevelCache) Clear(ctx context.Context) error

func (*MultiLevelCache) Close 

func (c *MultiLevelCache) Close() error

func (*MultiLevelCache) Delete 

func (c *MultiLevelCache) Delete(ctx context.Context, key string) error

func (*MultiLevelCache) Demote 

func (c *MultiLevelCache) Demote(ctx context.Context, key string) error

Demote moves a key from L1 to L2.

func (*MultiLevelCache) Exists 

func (c *MultiLevelCache) Exists(ctx context.Context, key string) bool

func (*MultiLevelCache) Get 

func (c *MultiLevelCache) Get(ctx context.Context, key string) (interface{}, error)

func (*MultiLevelCache) GetOrSet 

func (c *MultiLevelCache) GetOrSet(ctx context.Context, key string, fn func() (interface{}, error), ttl time.Duration) (interface{}, error)

GetOrSet retrieves a value or generates and stores it.

func (*MultiLevelCache) L1 

func (c *MultiLevelCache) L1() *LRUCache

L1 returns the L1 cache.

func (*MultiLevelCache) L2 

func (c *MultiLevelCache) L2() *DiskCache

L2 returns the L2 cache.

func (*MultiLevelCache) Set 

func (c *MultiLevelCache) Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error

func (*MultiLevelCache) SetL1Only 

func (c *MultiLevelCache) SetL1Only(ctx context.Context, key string, value interface{}, ttl time.Duration) error

SetL1Only sets a value only in L1.

func (*MultiLevelCache) SetL2Only 

func (c *MultiLevelCache) SetL2Only(ctx context.Context, key string, value interface{}, ttl time.Duration) error

SetL2Only sets a value only in L2.

func (*MultiLevelCache) Stats 

func (c *MultiLevelCache) Stats() MultiLevelStats

type MultiLevelConfig 

type MultiLevelConfig struct {
	L1 L1Config `yaml:"l1"`
	L2 L2Config `yaml:"l2"`
	// PromoteOnHit promotes entries from L2 to L1 on hit.
	PromoteOnHit bool `yaml:"promote_on_hit"`
	// WriteThrough writes to both L1 and L2 on set.
	WriteThrough bool `yaml:"write_through"`
}

MultiLevelConfig holds multi-level cache configuration.

func DefaultMultiLevelConfig 

func DefaultMultiLevelConfig() MultiLevelConfig

DefaultMultiLevelConfig returns the default multi-level cache configuration.

type MultiLevelStats 

type MultiLevelStats struct {
	L1Hits     int64
	L2Hits     int64
	Misses     int64
	Sets       int64
	Deletes    int64
	Promotions int64
}

MultiLevelStats holds stats for a multi-level cache.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.