Documentation
¶
Index ¶
- func NewShardedInMemoryCache[K comparable, V any](shards uint64, newCache func(shardIndex int) base.InMemoryCache[K, V], ...) base.InMemoryCache[K, V]
- type Hasher
- type ShardedInMemoryCache
- func (c *ShardedInMemoryCache[K, V]) Algorithm() string
- func (c *ShardedInMemoryCache[K, V]) Capacity() int
- func (c *ShardedInMemoryCache[K, V]) Delete(key K) bool
- func (c *ShardedInMemoryCache[K, V]) DeleteMany(keys []K) map[K]bool
- func (c *ShardedInMemoryCache[K, V]) Get(key K) (value V, ok bool)
- func (c *ShardedInMemoryCache[K, V]) GetMany(keys []K) (map[K]V, []K)
- func (c *ShardedInMemoryCache[K, V]) Has(key K) bool
- func (c *ShardedInMemoryCache[K, V]) HasMany(keys []K) map[K]bool
- func (c *ShardedInMemoryCache[K, V]) Keys() []K
- func (c *ShardedInMemoryCache[K, V]) Len() int
- func (c *ShardedInMemoryCache[K, V]) Peek(key K) (value V, ok bool)
- func (c *ShardedInMemoryCache[K, V]) PeekMany(keys []K) (map[K]V, []K)
- func (c *ShardedInMemoryCache[K, V]) Purge()
- func (c *ShardedInMemoryCache[K, V]) Range(f func(K, V) bool)
- func (c *ShardedInMemoryCache[K, V]) Set(key K, value V)
- func (c *ShardedInMemoryCache[K, V]) SetMany(items map[K]V)
- func (c *ShardedInMemoryCache[K, V]) SizeBytes() int64
- func (c *ShardedInMemoryCache[K, V]) Values() []V
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewShardedInMemoryCache ¶
func NewShardedInMemoryCache[K comparable, V any](shards uint64, newCache func(shardIndex int) base.InMemoryCache[K, V], fn Hasher[K]) base.InMemoryCache[K, V]
NewShardedInMemoryCache creates a sharded cache that distributes keys across multiple underlying cache instances for better concurrency performance. The cache uses a hash function to determine which shard each key belongs to. Each shard is an independent cache instance that can be accessed concurrently.
Types ¶
type Hasher ¶
Hasher is responsible for generating an unsigned 64-bit hash of the provided key. The hash function should minimize collisions to ensure even distribution across shards. For optimal performance, a fast hash function is preferable since it's called on every cache operation. The hash function should be deterministic - the same key should always produce the same hash.
type ShardedInMemoryCache ¶
type ShardedInMemoryCache[K comparable, V any] struct { // contains filtered or unexported fields }
ShardedInMemoryCache is a cache that distributes data across multiple shards to improve concurrency performance by reducing lock contention. Each shard is an independent cache instance that can be accessed concurrently without interfering with other shards.
func (*ShardedInMemoryCache[K, V]) Algorithm ¶
func (c *ShardedInMemoryCache[K, V]) Algorithm() string
Algorithm returns the name of the eviction algorithm used by the cache. This returns "sharded" to indicate the sharding mechanism.
func (*ShardedInMemoryCache[K, V]) Capacity ¶
func (c *ShardedInMemoryCache[K, V]) Capacity() int
Capacity returns the total capacity across all shards. This is the sum of the capacities of all individual cache shards.
func (*ShardedInMemoryCache[K, V]) Delete ¶
func (c *ShardedInMemoryCache[K, V]) Delete(key K) bool
Delete removes a key from the appropriate shard based on the key's hash. Returns true if the key was found and removed, false otherwise.
func (*ShardedInMemoryCache[K, V]) DeleteMany ¶
func (c *ShardedInMemoryCache[K, V]) DeleteMany(keys []K) map[K]bool
DeleteMany removes multiple keys by grouping them by shard for efficiency. Keys are hashed and grouped by their target shard, then each shard is updated with its respective keys in a single batch operation. Returns a map where keys are the input keys and values indicate if the key was found and removed. If the input slice is empty, returns an empty map immediately.
func (*ShardedInMemoryCache[K, V]) Get ¶
func (c *ShardedInMemoryCache[K, V]) Get(key K) (value V, ok bool)
Get retrieves a value from the appropriate shard based on the key's hash. Returns the value and a boolean indicating if the key was found.
func (*ShardedInMemoryCache[K, V]) GetMany ¶
func (c *ShardedInMemoryCache[K, V]) GetMany(keys []K) (map[K]V, []K)
GetMany retrieves multiple values by grouping keys by shard for efficiency. Keys are hashed and grouped by their target shard, then each shard is queried for its respective keys in a single batch operation. Returns a map of found key-value pairs and a slice of missing keys. If the input slice is empty, returns empty results immediately.
func (*ShardedInMemoryCache[K, V]) Has ¶
func (c *ShardedInMemoryCache[K, V]) Has(key K) bool
Has checks if a key exists in the appropriate shard based on the key's hash. Returns true if the key exists in the cache, false otherwise.
func (*ShardedInMemoryCache[K, V]) HasMany ¶
func (c *ShardedInMemoryCache[K, V]) HasMany(keys []K) map[K]bool
HasMany checks if multiple keys exist by grouping them by shard for efficiency. Keys are hashed and grouped by their target shard, then each shard is queried for its respective keys in a single batch operation. Returns a map where keys are the input keys and values indicate existence. If the input slice is empty, returns an empty map immediately.
func (*ShardedInMemoryCache[K, V]) Keys ¶
func (c *ShardedInMemoryCache[K, V]) Keys() []K
Keys returns all keys from all shards combined into a single slice. The order of keys in the returned slice is not guaranteed. Time complexity: O(n) where n is the total number of keys across all shards.
func (*ShardedInMemoryCache[K, V]) Len ¶
func (c *ShardedInMemoryCache[K, V]) Len() int
Len returns the total number of items across all shards. Time complexity: O(n) where n is the number of shards.
func (*ShardedInMemoryCache[K, V]) Peek ¶
func (c *ShardedInMemoryCache[K, V]) Peek(key K) (value V, ok bool)
Peek retrieves a value from the appropriate shard without updating access order. Returns the value and a boolean indicating if the key was found.
func (*ShardedInMemoryCache[K, V]) PeekMany ¶
func (c *ShardedInMemoryCache[K, V]) PeekMany(keys []K) (map[K]V, []K)
PeekMany retrieves multiple values without updating access order by grouping keys by shard. Keys are hashed and grouped by their target shard, then each shard is queried for its respective keys in a single batch operation. Returns a map of found key-value pairs and a slice of missing keys. If the input slice is empty, returns empty results immediately.
func (*ShardedInMemoryCache[K, V]) Purge ¶
func (c *ShardedInMemoryCache[K, V]) Purge()
Purge removes all keys and values from all shards. This operation clears all cache shards simultaneously.
func (*ShardedInMemoryCache[K, V]) Range ¶
func (c *ShardedInMemoryCache[K, V]) Range(f func(K, V) bool)
Range iterates over all key-value pairs from all shards. The iteration stops if the function returns false. The iteration order is not guaranteed and may not be consistent across calls.
func (*ShardedInMemoryCache[K, V]) Set ¶
func (c *ShardedInMemoryCache[K, V]) Set(key K, value V)
Set stores a key-value pair in the appropriate shard based on the key's hash. The key is hashed to determine which shard to use, providing O(1) average case performance.
func (*ShardedInMemoryCache[K, V]) SetMany ¶
func (c *ShardedInMemoryCache[K, V]) SetMany(items map[K]V)
SetMany stores multiple key-value pairs by grouping them by shard for efficiency. Keys are hashed and grouped by their target shard, then each shard is updated with its respective key-value pairs in a single batch operation. If the input map is empty, the operation is skipped entirely.
func (*ShardedInMemoryCache[K, V]) SizeBytes ¶ added in v0.7.0
func (c *ShardedInMemoryCache[K, V]) SizeBytes() int64
SizeBytes returns the total size of all cache entries in bytes across all shards. Time complexity: O(n) where n is the number of shards.
func (*ShardedInMemoryCache[K, V]) Values ¶
func (c *ShardedInMemoryCache[K, V]) Values() []V
Values returns all values from all shards combined into a single slice. The order of values in the returned slice is not guaranteed. Time complexity: O(n) where n is the total number of values across all shards.
Source Files