README
¶
MemoryCache
thread-safe cache with auto-delete
Documentation
¶
Index ¶
- Constants
- type Cache
- func (c *Cache[K, V]) Cap() int
- func (c *Cache[K, V]) Clear()
- func (c *Cache[K, V]) Close()
- func (c *Cache[K, V]) Del(k K)
- func (c *Cache[K, V]) ExpiredCount() int
- func (c *Cache[K, V]) Get(k K) (V, bool)
- func (c *Cache[K, V]) GetTTL(k K) (time.Duration, bool)
- func (c *Cache[K, V]) Len() int
- func (c *Cache[K, V]) Range(f func(key K, value V) bool)
- func (c *Cache[K, V]) RangeKeys(f func(key K) bool)
- func (c *Cache[K, V]) Set(k K, v V) bool
- func (c *Cache[K, V]) SetOrGet(k K, v V) bool
- func (c *Cache[K, V]) SetWithTTL(k K, v V, ttl time.Duration) bool
- func (c *Cache[K, V]) Size() int
- type ShardedCache
- func (sc *ShardedCache[K, V]) Clear()
- func (sc *ShardedCache[K, V]) Close()
- func (sc *ShardedCache[K, V]) Del(k K)
- func (sc *ShardedCache[K, V]) Get(k K) (V, bool)
- func (sc *ShardedCache[K, V]) GetTTL(k K) (time.Duration, bool)
- func (sc *ShardedCache[K, V]) Len() int
- func (sc *ShardedCache[K, V]) Range(f func(key K, value V) bool)
- func (sc *ShardedCache[K, V]) RangeParallel(f func(key K, value V) bool)
- func (sc *ShardedCache[K, V]) Set(k K, v V) bool
- func (sc *ShardedCache[K, V]) SetWithTTL(k K, v V, ttl time.Duration) bool
- type ShardedLFUCache
- func (sc *ShardedLFUCache[K, V]) Cap() int64
- func (sc *ShardedLFUCache[K, V]) Clear()
- func (sc *ShardedLFUCache[K, V]) Close()
- func (sc *ShardedLFUCache[K, V]) Del(k K)
- func (sc *ShardedLFUCache[K, V]) FlushAccessBuffers()
- func (sc *ShardedLFUCache[K, V]) Get(k K) (V, bool)
- func (sc *ShardedLFUCache[K, V]) GetTTL(k K) (time.Duration, bool)
- func (sc *ShardedLFUCache[K, V]) Len() int
- func (sc *ShardedLFUCache[K, V]) MaxCost() int64
- func (sc *ShardedLFUCache[K, V]) Range(f func(key K, value V) bool)
- func (sc *ShardedLFUCache[K, V]) RangeParallel(f func(key K, value V) bool)
- func (sc *ShardedLFUCache[K, V]) Set(k K, v V) bool
- func (sc *ShardedLFUCache[K, V]) SetWithCost(k K, v V, cost int64) bool
- func (sc *ShardedLFUCache[K, V]) SetWithTTL(k K, v V, ttl time.Duration) bool
- func (sc *ShardedLFUCache[K, V]) SetWithTTLAndCost(k K, v V, ttl time.Duration, cost int64) bool
- type UserCache
- func (c *UserCache[U, K, V]) Clear()
- func (c *UserCache[U, K, V]) Close()
- func (c *UserCache[U, K, V]) Config() UserCacheConfig
- func (c *UserCache[U, K, V]) Del(userID U, key K)
- func (c *UserCache[U, K, V]) DelUser(userID U)
- func (c *UserCache[U, K, V]) ForceSweep()
- func (c *UserCache[U, K, V]) Get(userID U, key K) (V, bool)
- func (c *UserCache[U, K, V]) GetAllSorted(userID U) []UserRecord[K, V]
- func (c *UserCache[U, K, V]) GetByKey(k K) (V, bool)
- func (c *UserCache[U, K, V]) GetLoadedCount(userID U) int64
- func (c *UserCache[U, K, V]) GetNewest(userID U, count int) []UserRecord[K, V]
- func (c *UserCache[U, K, V]) GetPage(userID U, offset, limit int) []UserRecord[K, V]
- func (c *UserCache[U, K, V]) GetUserRecordCount(userID U) int
- func (c *UserCache[U, K, V]) IsFullyLoaded(userID U) bool
- func (c *UserCache[U, K, V]) Len() int
- func (c *UserCache[U, K, V]) LoadMore(userID U, items []struct{ ... }) int
- func (c *UserCache[U, K, V]) LoadUserRecords(userID U, items []struct{ ... }) int
- func (c *UserCache[U, K, V]) Range(f func(userID U, key K, value V) bool)
- func (c *UserCache[U, K, V]) RangeByUser(userID U, f func(key K, value V) bool)
- func (c *UserCache[U, K, V]) RangeRecords(f func(userID U, record UserRecord[K, V]) bool)
- func (c *UserCache[U, K, V]) RangeUsers(f func(userID U, recordCount int) bool)
- func (c *UserCache[U, K, V]) ReplaceUserRecords(userID U, items []struct{ ... })
- func (c *UserCache[U, K, V]) Set(userID U, key K, value V, createdAt time.Time)
- func (c *UserCache[U, K, V]) SetFullyLoaded(userID U, fully bool)
- func (c *UserCache[U, K, V]) SetWithCost(userID U, key K, value V, createdAt time.Time, cost int64)
- func (c *UserCache[U, K, V]) UserCount() int
- type UserCacheConfig
- type UserRecord
Constants ¶
const ( LFU_SHARD_COUNT = 512 LFU_TOTAL = 1024_000 )
const SHARD_COUNT = 1024
const SHARD_MASK = SHARD_COUNT - 1
const TOTAL = 1024_000
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache[K comparable, V any] struct { // contains filtered or unexported fields }
func (*Cache[K, V]) ExpiredCount ¶
type ShardedCache ¶
type ShardedCache[K comparable, V any] struct { // contains filtered or unexported fields }
func NewShardedCache ¶
func NewShardedCache[K comparable, V any]() *ShardedCache[K, V]
func (*ShardedCache[K, V]) Clear ¶
func (sc *ShardedCache[K, V]) Clear()
func (*ShardedCache[K, V]) Close ¶
func (sc *ShardedCache[K, V]) Close()
func (*ShardedCache[K, V]) Del ¶
func (sc *ShardedCache[K, V]) Del(k K)
func (*ShardedCache[K, V]) Get ¶
func (sc *ShardedCache[K, V]) Get(k K) (V, bool)
func (*ShardedCache[K, V]) Len ¶
func (sc *ShardedCache[K, V]) Len() int
func (*ShardedCache[K, V]) Range ¶
func (sc *ShardedCache[K, V]) Range(f func(key K, value V) bool)
Range iterates over all items sequentially. The callback is called from a single goroutine, so no external synchronization needed. Return false from callback to stop iteration.
func (*ShardedCache[K, V]) RangeParallel ¶
func (sc *ShardedCache[K, V]) RangeParallel(f func(key K, value V) bool)
RangeParallel iterates over all items in parallel across shards. WARNING: The callback may be called from multiple goroutines simultaneously. Ensure your callback is thread-safe or use Range() for sequential iteration.
func (*ShardedCache[K, V]) Set ¶
func (sc *ShardedCache[K, V]) Set(k K, v V) bool
func (*ShardedCache[K, V]) SetWithTTL ¶
func (sc *ShardedCache[K, V]) SetWithTTL(k K, v V, ttl time.Duration) bool
type ShardedLFUCache ¶
type ShardedLFUCache[K comparable, V any] struct { // contains filtered or unexported fields }
ShardedLFUCache is a sharded cache with TinyLFU-based eviction.
func NewShardedLFUCache ¶
func NewShardedLFUCache[K comparable, V any]() *ShardedLFUCache[K, V]
NewShardedLFUCache creates a new sharded cache with LFU eviction.
func NewShardedLFUCacheWithSize ¶
func NewShardedLFUCacheWithSize[K comparable, V any](totalSize int64) *ShardedLFUCache[K, V]
NewShardedLFUCacheWithSize creates a new sharded LFU cache with specified total capacity.
func (*ShardedLFUCache[K, V]) Cap ¶
func (sc *ShardedLFUCache[K, V]) Cap() int64
Cap returns the remaining capacity across all shards.
func (*ShardedLFUCache[K, V]) Clear ¶
func (sc *ShardedLFUCache[K, V]) Clear()
Clear removes all items from the cache.
func (*ShardedLFUCache[K, V]) Close ¶
func (sc *ShardedLFUCache[K, V]) Close()
Close stops the cache cleanup routine and releases resources.
func (*ShardedLFUCache[K, V]) Del ¶
func (sc *ShardedLFUCache[K, V]) Del(k K)
Del removes an item from the cache.
func (*ShardedLFUCache[K, V]) FlushAccessBuffers ¶
func (sc *ShardedLFUCache[K, V]) FlushAccessBuffers()
FlushAccessBuffers forces all shards to process pending access buffers. Useful for testing when you need immediate frequency updates.
func (*ShardedLFUCache[K, V]) Get ¶
func (sc *ShardedLFUCache[K, V]) Get(k K) (V, bool)
Get retrieves an item from the cache.
func (*ShardedLFUCache[K, V]) GetTTL ¶
func (sc *ShardedLFUCache[K, V]) GetTTL(k K) (time.Duration, bool)
GetTTL returns the remaining TTL for an item.
func (*ShardedLFUCache[K, V]) Len ¶
func (sc *ShardedLFUCache[K, V]) Len() int
Len returns the total number of valid items in the cache.
func (*ShardedLFUCache[K, V]) MaxCost ¶
func (sc *ShardedLFUCache[K, V]) MaxCost() int64
MaxCost returns the maximum cost capacity across all shards.
func (*ShardedLFUCache[K, V]) Range ¶
func (sc *ShardedLFUCache[K, V]) Range(f func(key K, value V) bool)
Range iterates over all items sequentially. The callback is called from a single goroutine, so no external synchronization needed. Return false from callback to stop iteration.
func (*ShardedLFUCache[K, V]) RangeParallel ¶
func (sc *ShardedLFUCache[K, V]) RangeParallel(f func(key K, value V) bool)
RangeParallel iterates over all items in parallel across shards. WARNING: The callback may be called from multiple goroutines simultaneously. Ensure your callback is thread-safe or use Range() for sequential iteration.
func (*ShardedLFUCache[K, V]) Set ¶
func (sc *ShardedLFUCache[K, V]) Set(k K, v V) bool
Set adds an item to the cache with default cost of 1.
func (*ShardedLFUCache[K, V]) SetWithCost ¶
func (sc *ShardedLFUCache[K, V]) SetWithCost(k K, v V, cost int64) bool
SetWithCost adds an item with a specified cost.
func (*ShardedLFUCache[K, V]) SetWithTTL ¶
func (sc *ShardedLFUCache[K, V]) SetWithTTL(k K, v V, ttl time.Duration) bool
SetWithTTL adds an item with a TTL and default cost of 1.
func (*ShardedLFUCache[K, V]) SetWithTTLAndCost ¶
func (sc *ShardedLFUCache[K, V]) SetWithTTLAndCost(k K, v V, ttl time.Duration, cost int64) bool
SetWithTTLAndCost adds an item with both TTL and cost.
type UserCache ¶
type UserCache[U comparable, K comparable, V any] struct { // contains filtered or unexported fields }
UserCache is a cache with per-user record limits (no LFU eviction).
func NewUserCache ¶
func NewUserCache[U comparable, K comparable, V any](config UserCacheConfig) *UserCache[U, K, V]
NewUserCache creates a new cache with per-user limits.
func (*UserCache[U, K, V]) Clear ¶
func (c *UserCache[U, K, V]) Clear()
Clear removes all cached records.
func (*UserCache[U, K, V]) Close ¶
func (c *UserCache[U, K, V]) Close()
Close stops the cleanup routine.
func (*UserCache[U, K, V]) Config ¶
func (c *UserCache[U, K, V]) Config() UserCacheConfig
Config returns the cache configuration.
func (*UserCache[U, K, V]) Del ¶
func (c *UserCache[U, K, V]) Del(userID U, key K)
Del removes a record.
func (*UserCache[U, K, V]) DelUser ¶
func (c *UserCache[U, K, V]) DelUser(userID U)
DelUser removes all records for a user.
func (*UserCache[U, K, V]) ForceSweep ¶
func (c *UserCache[U, K, V]) ForceSweep()
ForceSweep runs cleanup immediately (for testing).
func (*UserCache[U, K, V]) GetAllSorted ¶
func (c *UserCache[U, K, V]) GetAllSorted(userID U) []UserRecord[K, V]
GetAllSorted returns all records for a user sorted by createdAt (newest first).
func (*UserCache[U, K, V]) GetByKey ¶
GetByKey retrieves a record by key only (without knowing userID). Uses globalKeyIdx for O(1) shard lookup.
func (*UserCache[U, K, V]) GetLoadedCount ¶
GetLoadedCount returns how many records were loaded via LoadMore for a user.
func (*UserCache[U, K, V]) GetNewest ¶
func (c *UserCache[U, K, V]) GetNewest(userID U, count int) []UserRecord[K, V]
GetNewest returns the N newest records for a user (sorted by createdAt desc).
func (*UserCache[U, K, V]) GetPage ¶
func (c *UserCache[U, K, V]) GetPage(userID U, offset, limit int) []UserRecord[K, V]
GetPage returns a page of records [offset, offset+limit) sorted by createdAt desc.
func (*UserCache[U, K, V]) GetUserRecordCount ¶
GetUserRecordCount returns the number of cached records for a user.
func (*UserCache[U, K, V]) IsFullyLoaded ¶
IsFullyLoaded returns whether all DB data has been loaded for a user.
func (*UserCache[U, K, V]) LoadMore ¶
func (c *UserCache[U, K, V]) LoadMore(userID U, items []struct { Key K Value V CreatedAt time.Time Cost int64 }) int
LoadMore adds a batch of records incrementally (pagination from DB). Returns the number of records actually loaded.
func (*UserCache[U, K, V]) LoadUserRecords ¶
func (c *UserCache[U, K, V]) LoadUserRecords(userID U, items []struct { Key K Value V CreatedAt time.Time Cost int64 }) int
LoadUserRecords loads multiple records for a user at once (for initial load from DB). All records get the same cached timestamp.
func (*UserCache[U, K, V]) Range ¶
Range iterates over all records in the cache. The callback receives userID, key, value for each record. Return false from the callback to stop iteration.
func (*UserCache[U, K, V]) RangeByUser ¶
RangeByUser iterates over all records for a specific user. Return false from the callback to stop iteration.
func (*UserCache[U, K, V]) RangeRecords ¶
func (c *UserCache[U, K, V]) RangeRecords(f func(userID U, record UserRecord[K, V]) bool)
RangeRecords iterates over all records with full metadata. The callback receives userID and UserRecord for each record. Return false from the callback to stop iteration.
func (*UserCache[U, K, V]) RangeUsers ¶
RangeUsers iterates over all users in the cache. The callback receives userID and record count for each user. Return false from the callback to stop iteration.
func (*UserCache[U, K, V]) ReplaceUserRecords ¶
func (c *UserCache[U, K, V]) ReplaceUserRecords(userID U, items []struct { Key K Value V CreatedAt time.Time Cost int64 })
ReplaceUserRecords replaces all records for a user.
func (*UserCache[U, K, V]) Set ¶
Set adds or updates a record for a user. Always accepts the record (no admission control).
func (*UserCache[U, K, V]) SetFullyLoaded ¶
SetFullyLoaded marks whether all DB data has been loaded for a user.
func (*UserCache[U, K, V]) SetWithCost ¶
SetWithCost adds or updates a record with specified cost.
type UserCacheConfig ¶
type UserCacheConfig struct {
// DefaultCachedCount - per-user cap for cached items.
DefaultCachedCount int
// SweepInterval - interval for periodic cleanup.
SweepInterval time.Duration
// CacheAgeDays - max cache item age (TTL in days).
CacheAgeDays int
// ShardCount - number of shards, must be power of two.
ShardCount int
}
UserCacheConfig is the configuration for UserCache.
func DefaultUserCacheConfig ¶
func DefaultUserCacheConfig() UserCacheConfig
DefaultUserCacheConfig returns default configuration.
type UserRecord ¶
type UserRecord[K comparable, V any] struct { Key K Value V CreatedAt time.Time CachedAt time.Time }
UserRecord represents a cached record with metadata.
Source Files