Documentation
¶
Index ¶
- Constants
- type FIFOCache
- func (c *FIFOCache[K, V]) All() map[K]V
- func (c *FIFOCache[K, V]) Delete(key K) bool
- func (c *FIFOCache[K, V]) DeleteOldest() (k K, v V, ok bool)
- func (c *FIFOCache[K, V]) Get(key K) (value V, ok bool)
- func (c *FIFOCache[K, V]) Has(key K) bool
- func (c *FIFOCache[K, V]) Keys() []K
- func (c *FIFOCache[K, V]) Len() int
- func (c *FIFOCache[K, V]) Peek(key K) (value V, ok bool)
- func (c *FIFOCache[K, V]) Purge()
- func (c *FIFOCache[K, V]) Range(f func(K, V) bool)
- func (c *FIFOCache[K, V]) Set(key K, value V)
- func (c *FIFOCache[K, V]) Values() []V
- type TwoQueueCache
- func New2QCache[K comparable, V any](capacity int) *TwoQueueCache[K, V]
- func New2QCacheWithEvictionCallback[K comparable, V any](capacity int, onEviction base.EvictionCallback[K, V]) *TwoQueueCache[K, V]
- func New2QCacheWithRatio[K comparable, V any](capacity int, recentRatio, ghostRatio float64) *TwoQueueCache[K, V]
- func New2QCacheWithRatioAndEvictionCallback[K comparable, V any](capacity int, recentRatio, ghostRatio float64, ...) *TwoQueueCache[K, V]
- func (c *TwoQueueCache[K, V]) Algorithm() string
- func (c *TwoQueueCache[K, V]) All() map[K]V
- func (c *TwoQueueCache[K, V]) Capacity() int
- func (c *TwoQueueCache[K, V]) Delete(key K) bool
- func (c *TwoQueueCache[K, V]) DeleteMany(keys []K) map[K]bool
- func (c *TwoQueueCache[K, V]) Get(key K) (value V, ok bool)
- func (c *TwoQueueCache[K, V]) GetMany(keys []K) (map[K]V, []K)
- func (c *TwoQueueCache[K, V]) Has(key K) bool
- func (c *TwoQueueCache[K, V]) HasMany(keys []K) map[K]bool
- func (c *TwoQueueCache[K, V]) Keys() []K
- func (c *TwoQueueCache[K, V]) Len() int
- func (c *TwoQueueCache[K, V]) Peek(key K) (value V, ok bool)
- func (c *TwoQueueCache[K, V]) PeekMany(keys []K) (map[K]V, []K)
- func (c *TwoQueueCache[K, V]) Purge()
- func (c *TwoQueueCache[K, V]) Range(f func(K, V) bool)
- func (c *TwoQueueCache[K, V]) Set(key K, value V)
- func (c *TwoQueueCache[K, V]) SetMany(items map[K]V)
- func (c *TwoQueueCache[K, V]) SizeBytes() int64
- func (c *TwoQueueCache[K, V]) Values() []V
Constants ¶
const ( // Default2QRecentRatio is the ratio of the 2Q cache dedicated // to recently added entries that have only been accessed once. // This is typically set to 25% of the total cache capacity. Default2QRecentRatio = 0.25 // Default2QGhostEntries is the default ratio of ghost // entries kept to track entries recently evicted. // This is typically set to 50% of the total cache capacity. Default2QGhostEntries = 0.50 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type FIFOCache ¶ added in v0.7.0
type FIFOCache[K comparable, V any] struct { // contains filtered or unexported fields }
FIFOCache implements a simple FIFO (First-In-First-Out) cache using a linked list. This is used for the recent and ghost components of the 2Q algorithm.
func (*FIFOCache[K, V]) All ¶ added in v0.9.0
func (c *FIFOCache[K, V]) All() map[K]V
All returns all key-value pairs in the FIFO cache.
func (*FIFOCache[K, V]) Delete ¶ added in v0.7.0
Delete removes a key from the FIFO cache. Returns true if the key was found and removed, false otherwise.
func (*FIFOCache[K, V]) DeleteOldest ¶ added in v0.7.0
DeleteOldest removes and returns the oldest item from the FIFO cache. Returns the key, value, and a boolean indicating if an item was removed.
func (*FIFOCache[K, V]) Get ¶ added in v0.7.0
Get retrieves a value from the FIFO cache. This operation does not change the position of the item in the FIFO order.
func (*FIFOCache[K, V]) Keys ¶ added in v0.7.0
func (c *FIFOCache[K, V]) Keys() []K
Keys returns all keys currently in the FIFO cache.
func (*FIFOCache[K, V]) Len ¶ added in v0.7.0
Len returns the current number of items in the FIFO cache.
func (*FIFOCache[K, V]) Peek ¶ added in v0.7.0
Peek retrieves a value from the FIFO cache without affecting the cache state.
func (*FIFOCache[K, V]) Purge ¶ added in v0.7.0
func (c *FIFOCache[K, V]) Purge()
Purge removes all keys and values from the FIFO cache.
func (*FIFOCache[K, V]) Range ¶ added in v0.7.0
Range iterates over all key-value pairs in the FIFO cache. The iteration stops if the function returns false.
type TwoQueueCache ¶
type TwoQueueCache[K comparable, V any] struct { // contains filtered or unexported fields }
TwoQueueCache implements the 2Q (Two-Queue) eviction algorithm, which is an enhancement over the standard LRU cache that tracks both frequently and recently used entries separately. This avoids a burst in access to new entries from evicting frequently used entries. The algorithm adds some additional tracking overhead but provides better cache performance for workloads with temporal locality patterns. TwoQueueCache is not safe for concurrent access.
func New2QCache ¶
func New2QCache[K comparable, V any](capacity int) *TwoQueueCache[K, V]
New2QCache creates a new 2Q cache with the specified capacity. Uses default ratios for recent entries (25%) and ghost entries (50%).
func New2QCacheWithEvictionCallback ¶ added in v0.2.0
func New2QCacheWithEvictionCallback[K comparable, V any](capacity int, onEviction base.EvictionCallback[K, V]) *TwoQueueCache[K, V]
New2QCacheWithEvictionCallback creates a new 2Q cache with the specified capacity and eviction callback. Uses default ratios for recent entries (25%) and ghost entries (50%). The callback will be called whenever an item is evicted from the cache.
func New2QCacheWithRatio ¶
func New2QCacheWithRatio[K comparable, V any](capacity int, recentRatio, ghostRatio float64) *TwoQueueCache[K, V]
New2QCacheWithRatio creates a new 2Q cache with the specified capacity and custom ratios. The recentRatio determines what portion of the cache is dedicated to recently accessed items. The ghostRatio determines what portion of the cache is used for tracking evicted items.
func New2QCacheWithRatioAndEvictionCallback ¶ added in v0.2.0
func New2QCacheWithRatioAndEvictionCallback[K comparable, V any](capacity int, recentRatio, ghostRatio float64, onEviction base.EvictionCallback[K, V]) *TwoQueueCache[K, V]
New2QCacheWithRatioAndEvictionCallback creates a new 2Q cache with the specified capacity, ratios, and eviction callback. This is the main constructor for 2Q caches. The 2Q algorithm separates items into three categories: recent, frequent, and ghost entries.
func (*TwoQueueCache[K, V]) Algorithm ¶
func (c *TwoQueueCache[K, V]) Algorithm() string
Algorithm returns the name of the eviction algorithm used by the cache. This is used for debugging and monitoring purposes.
func (*TwoQueueCache[K, V]) All ¶ added in v0.9.0
func (c *TwoQueueCache[K, V]) All() map[K]V
All returns all key-value pairs from both frequent and recent caches.
func (*TwoQueueCache[K, V]) Capacity ¶
func (c *TwoQueueCache[K, V]) Capacity() int
Capacity returns the total capacity of the cache. This is the sum of the capacities of all cache components.
func (*TwoQueueCache[K, V]) Delete ¶
func (c *TwoQueueCache[K, V]) Delete(key K) bool
Delete removes a key from all caches (frequent, recent, and ghost). Returns true if the key was found and removed from any cache, false otherwise.
func (*TwoQueueCache[K, V]) DeleteMany ¶
func (c *TwoQueueCache[K, V]) DeleteMany(keys []K) map[K]bool
DeleteMany removes multiple keys from all caches. Returns a map where keys are the input keys and values indicate if the key was found and removed.
func (*TwoQueueCache[K, V]) Get ¶
func (c *TwoQueueCache[K, V]) Get(key K) (value V, ok bool)
Get retrieves a value from the cache and may promote items between caches. If the key is in the frequent cache, it's returned directly. If the key is in the recent cache, it's promoted to the frequent cache. Returns the value and a boolean indicating if the key was found.
func (*TwoQueueCache[K, V]) GetMany ¶
func (c *TwoQueueCache[K, V]) GetMany(keys []K) (map[K]V, []K)
GetMany retrieves multiple values from the cache. Returns a map of found key-value pairs and a slice of missing keys. Items may be promoted between caches during this operation.
func (*TwoQueueCache[K, V]) Has ¶
func (c *TwoQueueCache[K, V]) Has(key K) bool
Has checks if a key exists in either the frequent or recent caches. This operation does not affect the cache state or promote items between caches.
func (*TwoQueueCache[K, V]) HasMany ¶
func (c *TwoQueueCache[K, V]) HasMany(keys []K) map[K]bool
HasMany checks if multiple keys exist in the cache. Returns a map where keys are the input keys and values indicate existence. This operation does not affect the cache state.
func (*TwoQueueCache[K, V]) Keys ¶
func (c *TwoQueueCache[K, V]) Keys() []K
Keys returns all keys from both frequent and recent caches combined. The order of keys in the returned slice is not guaranteed.
func (*TwoQueueCache[K, V]) Len ¶
func (c *TwoQueueCache[K, V]) Len() int
Len returns the total number of items across all caches. This is the sum of the lengths of frequent and recent caches (ghost cache not included).
func (*TwoQueueCache[K, V]) Peek ¶
func (c *TwoQueueCache[K, V]) Peek(key K) (value V, ok bool)
Peek retrieves a value from the cache without affecting the cache state. This operation does not promote items between caches or update access order. Returns the value and a boolean indicating if the key was found.
func (*TwoQueueCache[K, V]) PeekMany ¶
func (c *TwoQueueCache[K, V]) PeekMany(keys []K) (map[K]V, []K)
PeekMany retrieves multiple values from the cache without affecting the cache state. Returns a map of found key-value pairs and a slice of missing keys. This operation does not promote items between caches.
func (*TwoQueueCache[K, V]) Purge ¶
func (c *TwoQueueCache[K, V]) Purge()
Purge removes all keys and values from all caches. This operation clears the frequent, recent, and ghost caches simultaneously.
func (*TwoQueueCache[K, V]) Range ¶
func (c *TwoQueueCache[K, V]) Range(f func(K, V) bool)
Range iterates over all key-value pairs from both frequent and recent caches. The iteration stops if the function returns false. The iteration order is not guaranteed.
func (*TwoQueueCache[K, V]) Set ¶
func (c *TwoQueueCache[K, V]) Set(key K, value V)
Set stores a key-value pair in the cache using the 2Q algorithm. The algorithm determines where to place the item based on its access history: 1. If the key is already in the frequent cache, update its value 2. If the key is in the recent cache, promote it to the frequent cache 3. If the key is in the ghost cache, add it directly to the frequent cache 4. Otherwise, add it to the recent cache
func (*TwoQueueCache[K, V]) SetMany ¶
func (c *TwoQueueCache[K, V]) SetMany(items map[K]V)
SetMany stores multiple key-value pairs in the cache. This is more efficient than calling Set multiple times. Each key-value pair is processed individually according to the 2Q algorithm.
func (*TwoQueueCache[K, V]) SizeBytes ¶ added in v0.7.0
func (c *TwoQueueCache[K, V]) SizeBytes() int64
SizeBytes returns the total size of all cache entries in bytes. For generic caches, this returns 0 as the size cannot be determined without type information. Specialized implementations should override this method.
func (*TwoQueueCache[K, V]) Values ¶
func (c *TwoQueueCache[K, V]) Values() []V
Values returns all values from both frequent and recent caches combined. The order of values in the returned slice is not guaranteed.
Source Files