lru

Documentation

Index

• type Cache
  • func NewCache[K comparable, V any](capacity int) *Cache[K, V]
  • func (c *Cache[K, V]) Delete(key K)
  • func (c *Cache[K, V]) Get(key K) (v V, exists, expired bool)
  • func (c *Cache[K, V]) GetNotStale(key K) (v V, exists bool)
  • func (c *Cache[K, V]) GetQuiet(key K) (v V, exists, expired bool)
  • func (c *Cache[K, V]) GetWithTTL(key K) (v V, exists bool, ttl *time.Duration)
  • func (c *Cache[K, V]) Has(key K) (exists, expired bool)
  • func (c *Cache[K, V]) Len() (n int)
  • func (c *Cache[K, V]) MDelete(keys ...K)
  • func (c *Cache[K, V]) MGet(keys ...K) map[K]V
  • func (c *Cache[K, V]) MGetNotStale(keys ...K) map[K]V
  • func (c *Cache[K, V]) MSet(kvmap map[K]V, ttl time.Duration)
  • func (c *Cache[K, V]) Set(key K, value V, ttl time.Duration)
• type Interface
• type ShardedCache
  • func NewShardedCache[K comparable, V any](buckets, bucketCapacity int) *ShardedCache[K, V]
  • func (c *ShardedCache[K, V]) Delete(key K)
  • func (c *ShardedCache[K, V]) Get(key K) (v V, exists, expired bool)
  • func (c *ShardedCache[K, V]) GetNotStale(key K) (v V, exists bool)
  • func (c *ShardedCache[K, V]) GetQuiet(key K) (v V, exists, expired bool)
  • func (c *ShardedCache[K, V]) GetWithTTL(key K) (v V, exists bool, ttl *time.Duration)
  • func (c *ShardedCache[K, V]) Has(key K) (exists, expired bool)
  • func (c *ShardedCache[K, V]) Len() (n int)
  • func (c *ShardedCache[K, V]) MDelete(keys ...K)
  • func (c *ShardedCache[K, V]) MGet(keys ...K) map[K]V
  • func (c *ShardedCache[K, V]) MGetNotStale(keys ...K) map[K]V
  • func (c *ShardedCache[K, V]) MSet(kvmap map[K]V, ttl time.Duration)
  • func (c *ShardedCache[K, V]) Set(key K, value V, ttl time.Duration)

Types

type Cache

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

Cache is an in-memory cache using LRU algorithm.

It implements Interface in this package, see Interface for detailed api documents.

func NewCache

func NewCache[K comparable, V any](capacity int) *Cache[K, V]

NewCache returns a lru cache instance with given capacity, the underlying memory will be immediately allocated. For best performance, the memory will be reused and won't be freed for the lifetime of the cache.

Param capacity must be smaller than 2^32, else it will panic.

func (*Cache[K, V]) Delete

func (c *Cache[K, V]) Delete(key K)

func (*Cache[K, V]) Get

func (c *Cache[K, V]) Get(key K) (v V, exists, expired bool)

func (*Cache[K, V]) GetNotStale

func (c *Cache[K, V]) GetNotStale(key K) (v V, exists bool)

func (*Cache[K, V]) GetQuiet

func (c *Cache[K, V]) GetQuiet(key K) (v V, exists, expired bool)

func (*Cache[K, V]) GetWithTTL

func (c *Cache[K, V]) GetWithTTL(key K) (v V, exists bool, ttl *time.Duration)

func (*Cache[K, V]) Has

func (c *Cache[K, V]) Has(key K) (exists, expired bool)

func (*Cache[K, V]) Len

func (c *Cache[K, V]) Len() (n int)

func (*Cache[K, V]) MDelete

func (c *Cache[K, V]) MDelete(keys ...K)

func (*Cache[K, V]) MGet

func (c *Cache[K, V]) MGet(keys ...K) map[K]V

func (*Cache[K, V]) MGetNotStale

func (c *Cache[K, V]) MGetNotStale(keys ...K) map[K]V

func (*Cache[K, V]) MSet

func (c *Cache[K, V]) MSet(kvmap map[K]V, ttl time.Duration)

func (*Cache[K, V]) Set

func (c *Cache[K, V]) Set(key K, value V, ttl time.Duration)

type Interface

type Interface[K comparable, V any] interface {

	// Len returns the number of cached values.
	Len() int

	// Has checks if a key is in the cache and whether it is expired,
	// without updating its LRU score.
	Has(key K) (exists, expired bool)

	// Get returns the cached value for the given key and updates its LRU score.
	// The returned value may be expired, caller can check the returned value
	// "expired" to check whether the value is expired.
	Get(key K) (v V, exists, expired bool)

	// GetWithTTL returns the cached value for the given key and updates its
	// LRU score. The returned value may be expired, caller can check the
	// returned value "ttl" to check whether the value is expired.
	GetWithTTL(key K) (v V, exists bool, ttl *time.Duration)

	// GetQuiet returns the cached value for the given key, but don't modify its LRU score.
	// The returned value may be expired, caller can check the returned value
	// "expired" to check whether the value is expired.
	GetQuiet(key K) (v V, exists, expired bool)

	// GetNotStale returns the cached value for the given key. The returned value
	// is guaranteed not expired. If unexpired value available, its LRU score
	// will be updated.
	GetNotStale(key K) (v V, exists bool)

	// MGet returns map of cached values for the given interface keys and
	// update their LRU scores. The returned values may be expired.
	// It's a convenient and efficient way to retrieve multiple values.
	MGet(keys ...K) map[K]V

	// MGetNotStale is similar to MGet, but it returns only not stale values.
	MGetNotStale(keys ...K) map[K]V

	// Set adds an item to the cache overwriting existing one if it exists.
	Set(key K, value V, ttl time.Duration)

	// MSet adds multiple items to the cache overwriting existing ones.
	// Unlike calling Set multiple times, it acquires lock only once for
	// multiple key-value pairs.
	MSet(kvmap map[K]V, ttl time.Duration)

	// Delete removes a key from the cache if it exists.
	Delete(key K)

	// MDelete removes multiple interface keys from the cache if exists.
	// It's a convenient and efficient way to remove multiple keys.
	MDelete(keys ...K)
}

Interface is a generic abstract interface of the LRU cache implemented in this package.

type ShardedCache

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

ShardedCache is a hash-sharded version of Cache, it minimizes lock contention for heavy read workload. Generally Cache should be used instead of this unless you are sure that you are facing the lock contention problem.

It implements Interface in this package, see Interface for detailed api documents.

func NewShardedCache

func NewShardedCache[K comparable, V any](buckets, bucketCapacity int) *ShardedCache[K, V]

NewShardedCache returns a hash-sharded lru cache instance which is suitable to use for heavy lock contention use-case. It keeps same interface with the lru cache instance returned by NewCache function. Generally NewCache should be used instead of this unless you are sure that you are facing the lock contention problem.

func (*ShardedCache[K, V]) Delete

func (c *ShardedCache[K, V]) Delete(key K)

func (*ShardedCache[K, V]) Get

func (c *ShardedCache[K, V]) Get(key K) (v V, exists, expired bool)

func (*ShardedCache[K, V]) GetNotStale

func (c *ShardedCache[K, V]) GetNotStale(key K) (v V, exists bool)

func (*ShardedCache[K, V]) GetQuiet

func (c *ShardedCache[K, V]) GetQuiet(key K) (v V, exists, expired bool)

func (*ShardedCache[K, V]) GetWithTTL

func (c *ShardedCache[K, V]) GetWithTTL(key K) (v V, exists bool, ttl *time.Duration)

func (*ShardedCache[K, V]) Has

func (c *ShardedCache[K, V]) Has(key K) (exists, expired bool)

func (*ShardedCache[K, V]) Len

func (c *ShardedCache[K, V]) Len() (n int)

func (*ShardedCache[K, V]) MDelete

func (c *ShardedCache[K, V]) MDelete(keys ...K)

func (*ShardedCache[K, V]) MGet

func (c *ShardedCache[K, V]) MGet(keys ...K) map[K]V

func (*ShardedCache[K, V]) MGetNotStale

func (c *ShardedCache[K, V]) MGetNotStale(keys ...K) map[K]V

func (*ShardedCache[K, V]) MSet

func (c *ShardedCache[K, V]) MSet(kvmap map[K]V, ttl time.Duration)

func (*ShardedCache[K, V]) Set

func (c *ShardedCache[K, V]) Set(key K, value V, ttl time.Duration)