Documentation
¶
Overview ¶
Package cache contains in-process MRU/L1 cache implementations and utilities used by SOP. It offers a generic Cache interface and concrete MRU- and L1-based caches.
Package cache contains the L1 (MRU) cache implementation and L2 integration for B-tree nodes and handles.
Index ¶
- Variables
- func FormatNodeKey(k string) string
- func NewL2InMemoryCache() sop.L2Cache
- func NewStandaloneL2InMemoryCache() sop.L2Cache
- type Cache
- type L1Cache
- func (c *L1Cache) Count() int
- func (c *L1Cache) DeleteNodes(ctx context.Context, nodesIDs []sop.UUID) (bool, error)
- func (c *L1Cache) Evict()
- func (c *L1Cache) GetNode(ctx context.Context, handle sop.Handle, nodeTarget any, isNodeCacheTTL bool, ...) (any, error)
- func (c *L1Cache) GetNodeFromMRU(handle sop.Handle, nodeTarget any) any
- func (c *L1Cache) IsFull() bool
- func (c *L1Cache) SetNode(ctx context.Context, nodeID sop.UUID, node any, ...)
- func (c *L1Cache) SetNodeToMRU(ctx context.Context, nodeID sop.UUID, node any, ...)
- type L2InMemoryCache
- func (c *L2InMemoryCache) Clear(ctx context.Context) error
- func (c *L2InMemoryCache) CreateLockKeys(keys []string) []*sop.LockKey
- func (c *L2InMemoryCache) CreateLockKeysForIDs(keys []sop.Tuple[string, sop.UUID]) []*sop.LockKey
- func (c *L2InMemoryCache) Delete(ctx context.Context, keys []string) (bool, error)
- func (c *L2InMemoryCache) DualLock(ctx context.Context, duration time.Duration, lockKeys []*sop.LockKey) (bool, sop.UUID, error)
- func (c *L2InMemoryCache) FormatLockKey(k string) string
- func (c *L2InMemoryCache) Get(ctx context.Context, key string) (bool, string, error)
- func (c *L2InMemoryCache) GetEx(ctx context.Context, key string, expiration time.Duration) (bool, string, error)
- func (c *L2InMemoryCache) GetStruct(ctx context.Context, key string, target interface{}) (bool, error)
- func (c *L2InMemoryCache) GetStructEx(ctx context.Context, key string, target interface{}, expiration time.Duration) (bool, error)
- func (c *L2InMemoryCache) GetStructs(ctx context.Context, keys []string, targets []interface{}, ...) ([]bool, error)
- func (c *L2InMemoryCache) GetType() sop.L2CacheType
- func (c *L2InMemoryCache) Info(ctx context.Context, section string) (string, error)
- func (c *L2InMemoryCache) IsLocked(ctx context.Context, lockKeys []*sop.LockKey) (bool, error)
- func (c *L2InMemoryCache) IsLockedByOthers(ctx context.Context, lockKeyNames []string) (bool, error)
- func (c *L2InMemoryCache) IsLockedByOthersTTL(ctx context.Context, lockKeyNames []string, duration time.Duration) (bool, error)
- func (c *L2InMemoryCache) IsLockedTTL(ctx context.Context, duration time.Duration, lockKeys []*sop.LockKey) (bool, error)
- func (c *L2InMemoryCache) IsRestarted(ctx context.Context) bool
- func (c *L2InMemoryCache) Lock(ctx context.Context, duration time.Duration, lockKeys []*sop.LockKey) (bool, sop.UUID, error)
- func (c *L2InMemoryCache) Ping(ctx context.Context) error
- func (c *L2InMemoryCache) Set(ctx context.Context, key string, value string, expiration time.Duration) error
- func (c *L2InMemoryCache) SetStruct(ctx context.Context, key string, value interface{}, expiration time.Duration) error
- func (c *L2InMemoryCache) SetStructs(ctx context.Context, keys []string, values []interface{}, ...) error
- func (c *L2InMemoryCache) Unlock(ctx context.Context, lockKeys []*sop.LockKey) error
Constants ¶
This section is empty.
Variables ¶
var DefaultInMemoryCacheShardCapacity = 1000
DefaultInMemoryCacheShardCapacity is the default per-shard entry ceiling for the in-memory L2 cache. In standalone mode, L1 is intentionally smaller while L2 carries the broader hot-node working set. With 256 shards, this provides a total capacity of 256,000 entries (1000 × 256).
var DefaultMaxCapacity = 512
DefaultMaxCapacity is the default hard limit of entries allowed in the L1 cache.
var DefaultMinCapacity = 256
DefaultMinCapacity is the default minimum number of entries to retain before evictions are considered. Clustered deployments benefit from a larger L1 footprint because L2 (Redis) access has network latency.
var DefaultStandaloneMaxCapacity = 64
DefaultStandaloneMaxCapacity is the L1 cache ceiling for standalone/in-process usage.
var DefaultStandaloneMinCapacity = 32
DefaultStandaloneMinCapacity is the L1 cache footprint for standalone/in-process usage. Standalone uses a smaller L1 because L2 is also in-memory in the same process (deserialization only, no network).
Functions ¶
func FormatNodeKey ¶
FormatNodeKey prefixes the key with 'N' to form the cache key for a node.
func NewL2InMemoryCache ¶
func NewStandaloneL2InMemoryCache ¶
NewStandaloneL2InMemoryCache creates an in-memory L2 cache suitable for standalone processes.
Types ¶
type Cache ¶
type Cache[TK comparable, TV any] interface { // Clear removes all entries from the cache. Clear() // Set inserts or updates the given key/value pairs. Set(items []sop.KeyValuePair[TK, TV]) // Get looks up the values for the given keys; missing keys yield zero values. Get(keys []TK) []TV // Delete removes the given keys from the cache, if present. Delete(keys []TK) // Count returns the number of items currently stored in the cache. Count() int // IsFull reports whether the cache has reached its maximum capacity. IsFull() bool // Evict removes least-recently-used entries until capacity constraints are satisfied. Evict() }
Cache is a generic MRU cache interface used for in-memory caching scenarios. Implementations should maintain recency and support bulk operations.
func NewCache ¶
func NewCache[TK comparable, TV any](minCapacity, maxCapacity int) Cache[TK, TV]
NewCache creates a new generic cache with MRU-based eviction.
func NewSynchronizedCache ¶
func NewSynchronizedCache[TK comparable, TV any](minCapacity, maxCapacity int) Cache[TK, TV]
NewSynchronizedCache returns a thread-safe Cache instance backed by an MRU cache.
type L1Cache ¶
type L1Cache struct {
Handles Cache[sop.UUID, sop.Handle]
// contains filtered or unexported fields
}
L1Cache is an in-memory MRU cache for B-tree nodes and handle objects. It optionally integrates with an L2 cache (e.g., Redis) for cross-process sharing and TTL.
func GetGlobalL1Cache ¶
GetGlobalL1Cache returns the global L1 cache singleton, creating one on first use with the provided L2 cache and capacities appropriate for the deployment mode.
func NewL1Cache ¶
NewL1Cache constructs a new L1Cache with the given L2 cache and capacity bounds.
func (*L1Cache) DeleteNodes ¶
DeleteNodes removes the given node IDs from both the L1 MRU and the L2 cache. It returns true if any entries were removed and the last error encountered when deleting from L2.
func (*L1Cache) Evict ¶
func (c *L1Cache) Evict()
Evict removes least-recently-used entries until the cache is within capacity.
func (*L1Cache) GetNode ¶
func (c *L1Cache) GetNode(ctx context.Context, handle sop.Handle, nodeTarget any, isNodeCacheTTL bool, nodeCacheTTLDuration time.Duration) (any, error)
GetNode loads the node by handle either from L1 (if fresh) or from L2, honoring TTL semantics, and refreshes the entry in L1 before returning it.
func (*L1Cache) GetNodeFromMRU ¶
GetNodeFromMRU returns the node from L1 if the cached version matches the handle version; otherwise it returns nil.
type L2InMemoryCache ¶
type L2InMemoryCache struct {
// contains filtered or unexported fields
}
func (*L2InMemoryCache) CreateLockKeys ¶
func (c *L2InMemoryCache) CreateLockKeys(keys []string) []*sop.LockKey
func (*L2InMemoryCache) CreateLockKeysForIDs ¶
func (*L2InMemoryCache) FormatLockKey ¶
func (c *L2InMemoryCache) FormatLockKey(k string) string
func (*L2InMemoryCache) GetStructEx ¶
func (*L2InMemoryCache) GetStructs ¶
func (*L2InMemoryCache) GetType ¶
func (c *L2InMemoryCache) GetType() sop.L2CacheType
Returns InMemoryCache as L2Cache type.
func (*L2InMemoryCache) IsLockedByOthers ¶
func (*L2InMemoryCache) IsLockedByOthersTTL ¶
func (*L2InMemoryCache) IsLockedTTL ¶
func (*L2InMemoryCache) IsRestarted ¶
func (c *L2InMemoryCache) IsRestarted(ctx context.Context) bool
Source Files