cache

package
v0.0.0-...-440800f Latest Latest
Warning

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

Go to latest
Published: Oct 27, 2023 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package cache provides general-purpose in-memory caches. Different caches provide different eviction policies suitable for specific use cases.

Package cache implements a LRU cache.

The implementation borrows heavily from SmallLRUCache (originally by Nathan Schrenk). The object maintains a doubly-linked list of elements. When an element is accessed, it is promoted to the head of the list. When space is needed, the element at the tail of the list (the least recently used element) is evicted.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Cache

type Cache interface {

	// Set inserts an entry in the cache. This will replace any entry with
	// the same key that is already in the cache. The entry may be automatically
	// expunged from the cache at some point, depending on the eviction policies
	// of the cache and the options specified when the cache was created.
	Set(key interface{}, value interface{})

	// Get retrieves the value associated with the supplied key if the key
	// is present in the cache.
	Get(key interface{}) (value interface{}, ok bool)

	// Remove synchronously deletes the given key from the cache. This has no effect if the key is not
	// currently in the cache.
	Remove(key interface{})

	// RemoveAll synchronously deletes all entries from the cache.
	RemoveAll()

	// Stats returns information about the efficiency of the cache.
	Stats() Stats
}

Cache defines the standard behavior of in-memory thread-safe caches.

Different caches can have different eviction policies which determine when and how entries are automatically removed from the cache.

Using a cache is very simple:

  c := NewLRU(5*time.Second,     // default per-entry ttl
              5*time.Second,     // eviction interval
              500)               // max # of entries tracked
  c.Set("foo", "bar")			// add an entry
  value, ok := c.Get("foo")		// try to retrieve the entry
  if ok {
		fmt.Printf("Got value %v\n", value)
  } else {
     fmt.Printf("Value was not found, must have been evicted")
  }

type EvictionCallback

type EvictionCallback func(key, value interface{})

EvictionCallback is a function that will be called on entry eviction from an ExpiringCache.

This callback will be invoked immediately after the entry is deleted from the `sync.Map` that backs this cache (using `Map.Delete()`). No locks are held during the invocation of this callback. The callback should not result in blocking calls to long-running operations, however.

type ExpiringCache

type ExpiringCache interface {
	Cache

	// SetWithExpiration inserts an entry in the cache with a requested expiration time.
	// This will replace any entry with the same key that is already in the cache.
	// The entry will be automatically expunged from the cache at or slightly after the
	// requested expiration time.
	SetWithExpiration(key interface{}, value interface{}, expiration time.Duration)

	// EvictExpired() synchronously evicts all expired entries from the cache
	EvictExpired()
}

ExpiringCache is a cache with entries that are evicted over time

func NewLRU

func NewLRU(defaultExpiration time.Duration, evictionInterval time.Duration, maxEntries int32) ExpiringCache

NewLRU creates a new cache with an LRU and time-based eviction model.

Cache eviction is done on a periodic basis. Individual cache entries are evicted after their expiration time has passed. The periodic nature of eviction means that cache entries tend to survive around (expirationTime + (evictionInterval / 2))

In addition, when the cache is full, adding a new item will displace the item that has been referenced least recently.

defaultExpiration specifies the default minimum amount of time a cached entry remains in the cache before eviction. This value is used with the Set function. Explicit per-entry expiration times can be set with the SetWithExpiration function instead.

evictionInterval specifies the frequency at which eviction activities take place. This should likely be >= 1 second.

func NewTTL

func NewTTL(defaultExpiration time.Duration, evictionInterval time.Duration) ExpiringCache

NewTTL creates a new cache with a time-based eviction model.

Cache eviction is done on a periodic basis. Individual cache entries are evicted after their expiration time has passed. The periodic nature of eviction means that cache entries tend to survive around (expirationTime + (evictionInterval / 2))

defaultExpiration specifies the default minimum amount of time a cached entry remains in the cache before eviction. This value is used with the Set function. Explicit per-entry expiration times can be set with the SetWithExpiration function instead.

evictionInterval specifies the frequency at which eviction activities take place. This should likely be >= 1 second.

Since TTL caches only evict data based on the passage of time, it's possible to use up all available memory by continuing to add entries to the cache with a long enough expiration time. Don't do that.

func NewTTLWithCallback

func NewTTLWithCallback(defaultExpiration time.Duration, evictionInterval time.Duration, callback EvictionCallback) ExpiringCache

NewTTLWithCallback creates a new cache with a time-based eviction model that will invoke the supplied callback on all evictions. See also: NewTTL.

type Item

type Item struct {
	Key   string
	Value Value
}

Item is what is stored in the cache

type LRUCache

type LRUCache struct {
	// contains filtered or unexported fields
}

LRUCache is a typical LRU cache implementation. If the cache reaches the capacity, the least recently used item is deleted from the cache. Note the capacity is not the number of items, but the total sum of the Size() of each item.

func NewLRUCache

func NewLRUCache(capacity int64) *LRUCache

NewLRUCache creates a new empty cache with the given capacity.

func (*LRUCache) Capacity

func (lru *LRUCache) Capacity() int64

Capacity returns the cache maximum capacity.

func (*LRUCache) Clear

func (lru *LRUCache) Clear()

Clear will clear the entire cache.

func (*LRUCache) Delete

func (lru *LRUCache) Delete(key string) bool

Delete removes an entry from the cache, and returns if the entry existed.

func (*LRUCache) Evictions

func (lru *LRUCache) Evictions() int64

Evictions returns the eviction count.

func (*LRUCache) Get

func (lru *LRUCache) Get(key string) (v Value, ok bool)

Get returns a value from the cache, and marks the entry as most recently used.

func (*LRUCache) Items

func (lru *LRUCache) Items() []Item

Items returns all the values for the cache, ordered from most recently used to least recently used.

func (*LRUCache) Keys

func (lru *LRUCache) Keys() []string

Keys returns all the keys for the cache, ordered from most recently used to least recently used.

func (*LRUCache) Length

func (lru *LRUCache) Length() int64

Length returns how many elements are in the cache

func (*LRUCache) Oldest

func (lru *LRUCache) Oldest() (oldest time.Time)

Oldest returns the insertion time of the oldest element in the cache, or a IsZero() time if cache is empty.

func (*LRUCache) Peek

func (lru *LRUCache) Peek(key string) (v Value, ok bool)

Peek returns a value from the cache without changing the LRU order.

func (*LRUCache) Set

func (lru *LRUCache) Set(key string, value Value)

Set sets a value in the cache.

func (*LRUCache) SetCapacity

func (lru *LRUCache) SetCapacity(capacity int64)

SetCapacity will set the capacity of the cache. If the capacity is smaller, and the current cache size exceed that capacity, the cache will be shrank.

func (*LRUCache) SetIfAbsent

func (lru *LRUCache) SetIfAbsent(key string, value Value)

SetIfAbsent will set the value in the cache if not present. If the value exists in the cache, we don't set it.

func (*LRUCache) Size

func (lru *LRUCache) Size() int64

Size returns the sum of the objects' Size() method.

func (*LRUCache) Stats

func (lru *LRUCache) Stats() (length, size, capacity, evictions int64, oldest time.Time)

Stats returns a few stats on the cache.

func (*LRUCache) StatsJSON

func (lru *LRUCache) StatsJSON() string

StatsJSON returns stats as a JSON object in a string.

type Stats

type Stats struct {
	// Writes captures the number of times state in the cache was added or updated.
	Writes uint64

	// Hits captures the number of times a Get operation succeeded to find an entry in the cache.
	Hits uint64

	// Misses captures the number of times a Get operation failed to find an entry in the cache.
	Misses uint64

	// Evictions captures the number of entries that have been evicted from the cache
	Evictions uint64

	// Removals captures the number of entries that have been explicitly removed from the
	// cache
	Removals uint64
}

Stats returns usage statistics about an individual cache, useful to assess the efficiency of a cache.

The values returned in this struct are approximations of the current state of the cache. For the sake of efficiency, certain edge cases in the implementation can lead to inaccuracies.

type Value

type Value interface {
	// Size returns how big this value is. If you want to just track
	// the cache by number of objects, you may return the size as 1.
	Size() int
}

Value is the interface values that go into LRUCache need to satisfy

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL