freelru

package
v0.6.0-beta.2 Latest Latest
Warning

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

 Go to latest Published: Nov 28, 2024 License: GPL-2.0, Apache-2.0 Imports: 7 Imported by: 0

README

freelru

upstream: github.com/elastic/go-freelru@v0.16.0 source: github.com/sagernet/go-freelru@1b34934a560d528d1866415d440625ed2a2560fe

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Cache 

type Cache[K comparable, V comparable] interface {
	// SetLifetime sets the default lifetime of LRU elements.
	// Lifetime 0 means "forever".
	SetLifetime(lifetime time.Duration)

	// SetOnEvict sets the OnEvict callback function.
	// The onEvict function is called for each evicted lru entry.
	SetOnEvict(onEvict OnEvictCallback[K, V])

	SetHealthCheck(healthCheck HealthCheckCallback[K, V])

	// Len returns the number of elements stored in the cache.
	Len() int

	// AddWithLifetime adds a key:value to the cache with a lifetime.
	// Returns true, true if key was updated and eviction occurred.
	AddWithLifetime(key K, value V, lifetime time.Duration) (evicted bool)

	// Add adds a key:value to the cache.
	// Returns true, true if key was updated and eviction occurred.
	Add(key K, value V) (evicted bool)

	// Get returns the value associated with the key, setting it as the most
	// recently used item.
	// If the found cache item is already expired, the evict function is called
	// and the return value indicates that the key was not found.
	Get(key K) (V, bool)

	GetWithLifetime(key K) (V, time.Time, bool)

	// GetAndRefresh returns the value associated with the key, setting it as the most
	// recently used item.
	// The lifetime of the found cache item is refreshed, even if it was already expired.
	GetAndRefresh(key K) (V, bool)

	GetAndRefreshOrAdd(key K, constructor func() (V, bool)) (V, bool)

	// Peek looks up a key's value from the cache, without changing its recent-ness.
	// If the found entry is already expired, the evict function is called.
	Peek(key K) (V, bool)

	PeekWithLifetime(key K) (V, time.Time, bool)

	UpdateLifetime(key K, value V, lifetime time.Duration) bool

	// Contains checks for the existence of a key, without changing its recent-ness.
	// If the found entry is already expired, the evict function is called.
	Contains(key K) bool

	// Remove removes the key from the cache.
	// The return value indicates whether the key existed or not.
	// The evict function is called for the removed entry.
	Remove(key K) bool

	// RemoveOldest removes the oldest entry from the cache.
	// Key, value and an indicator of whether the entry has been removed is returned.
	// The evict function is called for the removed entry.
	RemoveOldest() (key K, value V, removed bool)

	// Keys returns a slice of the keys in the cache, from oldest to newest.
	// Expired entries are not included.
	// The evict function is called for each expired item.
	Keys() []K

	// Purge purges all data (key and value) from the LRU.
	// The evict function is called for each expired item.
	// The LRU metrics are reset.
	Purge()

	// PurgeExpired purges all expired items from the LRU.
	// The evict function is called for each expired item.
	PurgeExpired()

	// Metrics returns the metrics of the cache.
	Metrics() Metrics

	// ResetMetrics resets the metrics of the cache and returns the previous state.
	ResetMetrics() Metrics
}

type HashKeyCallback 

type HashKeyCallback[K comparable] func(K) uint32

HashKeyCallback is the function that creates a hash from the passed key.

type HealthCheckCallback 

type HealthCheckCallback[K comparable, V comparable] func(K, V) bool

type LRU 

type LRU[K comparable, V comparable] struct {
	// contains filtered or unexported fields
}

LRU implements a non-thread safe fixed size LRU cache.

func New 

func New[K comparable, V comparable](capacity uint32, hash HashKeyCallback[K]) (*LRU[K, V], error)

New constructs an LRU with the given capacity of elements. The hash function calculates a hash value from the keys.

func NewWithSize 

func NewWithSize[K comparable, V comparable](capacity, size uint32, hash HashKeyCallback[K]) (
	*LRU[K, V], error,
)

NewWithSize constructs an LRU with the given capacity and size. The hash function calculates a hash value from the keys. A size greater than the capacity increases memory consumption and decreases the CPU consumption by reducing the chance of collisions. Size must not be lower than the capacity.

func (*LRU[K, V]) Add 

func (lru *LRU[K, V]) Add(key K, value V) (evicted bool)

Add adds a key:value to the cache. Returns true, true if key was updated and eviction occurred.

func (*LRU[K, V]) AddWithLifetime 

func (lru *LRU[K, V]) AddWithLifetime(key K, value V, lifetime time.Duration) (evicted bool)

AddWithLifetime adds a key:value to the cache with a lifetime. Returns true, true if key was updated and eviction occurred.

func (*LRU[K, V]) Contains 

func (lru *LRU[K, V]) Contains(key K) (ok bool)

Contains checks for the existence of a key, without changing its recent-ness. If the found entry is already expired, the evict function is called.

func (*LRU[K, V]) Get 

func (lru *LRU[K, V]) Get(key K) (value V, ok bool)

Get returns the value associated with the key, setting it as the most recently used item. If the found cache item is already expired, the evict function is called and the return value indicates that the key was not found.

func (*LRU[K, V]) GetAndRefresh 

func (lru *LRU[K, V]) GetAndRefresh(key K) (V, bool)

GetAndRefresh returns the value associated with the key, setting it as the most recently used item. The lifetime of the found cache item is refreshed, even if it was already expired.

func (*LRU[K, V]) GetAndRefreshOrAdd 

func (lru *LRU[K, V]) GetAndRefreshOrAdd(key K, constructor func() (V, bool)) (V, bool)

func (*LRU[K, V]) GetWithLifetime 

func (lru *LRU[K, V]) GetWithLifetime(key K) (value V, lifetime time.Time, ok bool)

func (*LRU[K, V]) Keys 

func (lru *LRU[K, V]) Keys() []K

Keys returns a slice of the keys in the cache, from oldest to newest. Expired entries are not included. The evict function is called for each expired item.

func (*LRU[K, V]) Len 

func (lru *LRU[K, V]) Len() int

Len returns the number of elements stored in the cache.

func (*LRU[K, V]) Metrics 

func (lru *LRU[K, V]) Metrics() Metrics

Metrics returns the metrics of the cache.

func (*LRU[K, V]) Peek 

func (lru *LRU[K, V]) Peek(key K) (value V, ok bool)

Peek looks up a key's value from the cache, without changing its recent-ness. If the found entry is already expired, the evict function is called.

func (*LRU[K, V]) PeekWithLifetime 

func (lru *LRU[K, V]) PeekWithLifetime(key K) (value V, lifetime time.Time, ok bool)

func (*LRU[K, V]) PrintStats 

func (lru *LRU[K, V]) PrintStats()

func (*LRU[K, V]) Purge 

func (lru *LRU[K, V]) Purge()

Purge purges all data (key and value) from the LRU. The evict function is called for each expired item. The LRU metrics are reset.

func (*LRU[K, V]) PurgeExpired 

func (lru *LRU[K, V]) PurgeExpired()

PurgeExpired purges all expired items from the LRU. The evict function is called for each expired item.

func (*LRU[K, V]) Remove 

func (lru *LRU[K, V]) Remove(key K) (removed bool)

Remove removes the key from the cache. The return value indicates whether the key existed or not. The evict function is called for the removed entry.

func (*LRU[K, V]) RemoveOldest 

func (lru *LRU[K, V]) RemoveOldest() (key K, value V, removed bool)

RemoveOldest removes the oldest entry from the cache. Key, value and an indicator of whether the entry has been removed is returned. The evict function is called for the removed entry.

func (*LRU[K, V]) ResetMetrics 

func (lru *LRU[K, V]) ResetMetrics() Metrics

ResetMetrics resets the metrics of the cache and returns the previous state.

func (*LRU[K, V]) SetHealthCheck 

func (lru *LRU[K, V]) SetHealthCheck(healthCheck HealthCheckCallback[K, V])

func (*LRU[K, V]) SetLifetime 

func (lru *LRU[K, V]) SetLifetime(lifetime time.Duration)

SetLifetime sets the default lifetime of LRU elements. Lifetime 0 means "forever".

func (*LRU[K, V]) SetOnEvict 

func (lru *LRU[K, V]) SetOnEvict(onEvict OnEvictCallback[K, V])

SetOnEvict sets the OnEvict callback function. The onEvict function is called for each evicted lru entry. Eviction happens - when the cache is full and a new entry is added (oldest entry is evicted) - when an entry is removed by Remove() or RemoveOldest() - when an entry is recognized as expired - when Purge() is called

func (*LRU[K, V]) UpdateLifetime 

func (lru *LRU[K, V]) UpdateLifetime(key K, value V, lifetime time.Duration) bool

type Metrics 

type Metrics struct {
	Inserts    uint64
	Collisions uint64
	Evictions  uint64
	Removals   uint64
	Hits       uint64
	Misses     uint64
}

Metrics contains metrics about the cache.

type OnEvictCallback 

type OnEvictCallback[K comparable, V comparable] func(K, V)

OnEvictCallback is the type for the eviction function.

type ShardedLRU 

type ShardedLRU[K comparable, V comparable] struct {
	// contains filtered or unexported fields
}

ShardedLRU is a thread-safe, sharded, fixed size LRU cache. Sharding is used to reduce lock contention on high concurrency. The downside is that exact LRU behavior is not given (as for the LRU and SynchedLRU types).

func NewSharded 

func NewSharded[K comparable, V comparable](capacity uint32, hash HashKeyCallback[K]) (*ShardedLRU[K, V],
	error,
)

NewSharded creates a new thread-safe sharded LRU hashmap with the given capacity.

func NewShardedWithSize 

func NewShardedWithSize[K comparable, V comparable](shards, capacity, size uint32,
	hash HashKeyCallback[K]) (
	*ShardedLRU[K, V], error,
)

func (*ShardedLRU[K, V]) Add 

func (lru *ShardedLRU[K, V]) Add(key K, value V) (evicted bool)

Add adds a key:value to the cache. Returns true, true if key was updated and eviction occurred.

func (*ShardedLRU[K, V]) AddWithLifetime 

func (lru *ShardedLRU[K, V]) AddWithLifetime(key K, value V,
	lifetime time.Duration,
) (evicted bool)

AddWithLifetime adds a key:value to the cache with a lifetime. Returns true, true if key was updated and eviction occurred.

func (*ShardedLRU[K, V]) Contains 

func (lru *ShardedLRU[K, V]) Contains(key K) (ok bool)

Contains checks for the existence of a key, without changing its recent-ness. If the found entry is already expired, the evict function is called.

func (*ShardedLRU[K, V]) Get 

func (lru *ShardedLRU[K, V]) Get(key K) (value V, ok bool)

Get returns the value associated with the key, setting it as the most recently used item. If the found cache item is already expired, the evict function is called and the return value indicates that the key was not found.

func (*ShardedLRU[K, V]) GetAndRefresh 

func (lru *ShardedLRU[K, V]) GetAndRefresh(key K) (value V, ok bool)

GetAndRefresh returns the value associated with the key, setting it as the most recently used item. The lifetime of the found cache item is refreshed, even if it was already expired.

func (*ShardedLRU[K, V]) GetAndRefreshOrAdd 

func (lru *ShardedLRU[K, V]) GetAndRefreshOrAdd(key K, constructor func() (V, bool)) (value V, updated bool)

func (*ShardedLRU[K, V]) GetWithLifetime 

func (lru *ShardedLRU[K, V]) GetWithLifetime(key K) (value V, lifetime time.Time, ok bool)

func (*ShardedLRU[K, V]) Keys 

func (lru *ShardedLRU[K, V]) Keys() []K

Keys returns a slice of the keys in the cache, from oldest to newest. Expired entries are not included. The evict function is called for each expired item.

func (*ShardedLRU[K, V]) Len 

func (lru *ShardedLRU[K, V]) Len() (length int)

Len returns the number of elements stored in the cache.

func (*ShardedLRU[K, V]) Metrics 

func (lru *ShardedLRU[K, V]) Metrics() Metrics

Metrics returns the metrics of the cache.

func (*ShardedLRU[K, V]) Peek 

func (lru *ShardedLRU[K, V]) Peek(key K) (value V, ok bool)

Peek looks up a key's value from the cache, without changing its recent-ness. If the found entry is already expired, the evict function is called.

func (*ShardedLRU[K, V]) PeekWithLifetime 

func (lru *ShardedLRU[K, V]) PeekWithLifetime(key K) (value V, lifetime time.Time, ok bool)

func (*ShardedLRU[K, V]) PrintStats 

func (lru *ShardedLRU[K, V]) PrintStats()

func (*ShardedLRU[K, V]) Purge 

func (lru *ShardedLRU[K, V]) Purge()

Purge purges all data (key and value) from the LRU. The evict function is called for each expired item. The LRU metrics are reset.

func (*ShardedLRU[K, V]) PurgeExpired 

func (lru *ShardedLRU[K, V]) PurgeExpired()

PurgeExpired purges all expired items from the LRU. The evict function is called for each expired item.

func (*ShardedLRU[K, V]) Remove 

func (lru *ShardedLRU[K, V]) Remove(key K) (removed bool)

Remove removes the key from the cache. The return value indicates whether the key existed or not. The evict function is called for the removed entry.

func (*ShardedLRU[K, V]) RemoveOldest 

func (lru *ShardedLRU[K, V]) RemoveOldest() (key K, value V, removed bool)

RemoveOldest removes the oldest entry from the cache. Key, value and an indicator of whether the entry has been removed is returned. The evict function is called for the removed entry.

func (*ShardedLRU[K, V]) ResetMetrics 

func (lru *ShardedLRU[K, V]) ResetMetrics() Metrics

ResetMetrics resets the metrics of the cache and returns the previous state.

func (*ShardedLRU[K, V]) SetHealthCheck 

func (lru *ShardedLRU[K, V]) SetHealthCheck(healthCheck HealthCheckCallback[K, V])

func (*ShardedLRU[K, V]) SetLifetime 

func (lru *ShardedLRU[K, V]) SetLifetime(lifetime time.Duration)

SetLifetime sets the default lifetime of LRU elements. Lifetime 0 means "forever".

func (*ShardedLRU[K, V]) SetOnEvict 

func (lru *ShardedLRU[K, V]) SetOnEvict(onEvict OnEvictCallback[K, V])

SetOnEvict sets the OnEvict callback function. The onEvict function is called for each evicted lru entry.

func (*ShardedLRU[K, V]) UpdateLifetime 

func (lru *ShardedLRU[K, V]) UpdateLifetime(key K, value V, lifetime time.Duration) (ok bool)

type SyncedLRU 

type SyncedLRU[K comparable, V comparable] struct {
	// contains filtered or unexported fields
}

func NewSynced 

func NewSynced[K comparable, V comparable](capacity uint32, hash HashKeyCallback[K]) (*SyncedLRU[K, V],
	error,
)

NewSynced creates a new thread-safe LRU hashmap with the given capacity.

func NewSyncedWithSize 

func NewSyncedWithSize[K comparable, V comparable](capacity, size uint32,
	hash HashKeyCallback[K],
) (*SyncedLRU[K, V], error)

func (*SyncedLRU[K, V]) Add 

func (lru *SyncedLRU[K, V]) Add(key K, value V) (evicted bool)

Add adds a key:value to the cache. Returns true, true if key was updated and eviction occurred.

func (*SyncedLRU[K, V]) AddWithLifetime 

func (lru *SyncedLRU[K, V]) AddWithLifetime(key K, value V, lifetime time.Duration) (evicted bool)

AddWithLifetime adds a key:value to the cache with a lifetime. Returns true, true if key was updated and eviction occurred.

func (*SyncedLRU[K, V]) Contains 

func (lru *SyncedLRU[K, V]) Contains(key K) (ok bool)

Contains checks for the existence of a key, without changing its recent-ness. If the found entry is already expired, the evict function is called.

func (*SyncedLRU[K, V]) Get 

func (lru *SyncedLRU[K, V]) Get(key K) (value V, ok bool)

Get returns the value associated with the key, setting it as the most recently used item. If the found cache item is already expired, the evict function is called and the return value indicates that the key was not found.

func (*SyncedLRU[K, V]) GetAndRefresh 

func (lru *SyncedLRU[K, V]) GetAndRefresh(key K) (value V, ok bool)

GetAndRefresh returns the value associated with the key, setting it as the most recently used item. The lifetime of the found cache item is refreshed, even if it was already expired.

func (*SyncedLRU[K, V]) GetAndRefreshOrAdd 

func (lru *SyncedLRU[K, V]) GetAndRefreshOrAdd(key K, constructor func() (V, bool)) (value V, updated bool)

func (*SyncedLRU[K, V]) GetWithLifetime 

func (lru *SyncedLRU[K, V]) GetWithLifetime(key K) (value V, lifetime time.Time, ok bool)

func (*SyncedLRU[K, V]) Keys 

func (lru *SyncedLRU[K, V]) Keys() (keys []K)

Keys returns a slice of the keys in the cache, from oldest to newest. Expired entries are not included. The evict function is called for each expired item.

func (*SyncedLRU[K, V]) Len 

func (lru *SyncedLRU[K, V]) Len() (length int)

Len returns the number of elements stored in the cache.

func (*SyncedLRU[K, V]) Metrics 

func (lru *SyncedLRU[K, V]) Metrics() Metrics

Metrics returns the metrics of the cache.

func (*SyncedLRU[K, V]) Peek 

func (lru *SyncedLRU[K, V]) Peek(key K) (value V, ok bool)

Peek looks up a key's value from the cache, without changing its recent-ness. If the found entry is already expired, the evict function is called.

func (*SyncedLRU[K, V]) PeekWithLifetime 

func (lru *SyncedLRU[K, V]) PeekWithLifetime(key K) (value V, lifetime time.Time, ok bool)

func (*SyncedLRU[K, V]) PrintStats 

func (lru *SyncedLRU[K, V]) PrintStats()

func (*SyncedLRU[K, V]) Purge 

func (lru *SyncedLRU[K, V]) Purge()

Purge purges all data (key and value) from the LRU. The evict function is called for each expired item. The LRU metrics are reset.

func (*SyncedLRU[K, V]) PurgeExpired 

func (lru *SyncedLRU[K, V]) PurgeExpired()

PurgeExpired purges all expired items from the LRU. The evict function is called for each expired item.

func (*SyncedLRU[K, V]) Remove 

func (lru *SyncedLRU[K, V]) Remove(key K) (removed bool)

Remove removes the key from the cache. The return value indicates whether the key existed or not. The evict function is being called if the key existed.

func (*SyncedLRU[K, V]) RemoveOldest 

func (lru *SyncedLRU[K, V]) RemoveOldest() (key K, value V, removed bool)

RemoveOldest removes the oldest entry from the cache. Key, value and an indicator of whether the entry has been removed is returned. The evict function is called for the removed entry.

func (*SyncedLRU[K, V]) ResetMetrics 

func (lru *SyncedLRU[K, V]) ResetMetrics() Metrics

ResetMetrics resets the metrics of the cache and returns the previous state.

func (*SyncedLRU[K, V]) SetHealthCheck 

func (lru *SyncedLRU[K, V]) SetHealthCheck(healthCheck HealthCheckCallback[K, V])

func (*SyncedLRU[K, V]) SetLifetime 

func (lru *SyncedLRU[K, V]) SetLifetime(lifetime time.Duration)

SetLifetime sets the default lifetime of LRU elements. Lifetime 0 means "forever".

func (*SyncedLRU[K, V]) SetOnEvict 

func (lru *SyncedLRU[K, V]) SetOnEvict(onEvict OnEvictCallback[K, V])

SetOnEvict sets the OnEvict callback function. The onEvict function is called for each evicted lru entry.

func (*SyncedLRU[K, V]) UpdateLifetime 

func (lru *SyncedLRU[K, V]) UpdateLifetime(key K, value V, lifetime time.Duration) (ok bool)

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.