cache

Documentation

Overview

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

Index

• type Cache
• type ExpiringCache
  • func NewLRU(defaultExpiration time.Duration, evictionInterval time.Duration, ...) ExpiringCache
  • func NewTTL(defaultExpiration time.Duration, evictionInterval time.Duration) ExpiringCache
• type Stats

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{})

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

Cache defines the standard behavior of in-memory caches.

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

Ideas for the future:

• Return the number of entries in the cache in stats.
• Provide an eviction callback to know when entries are evicted.
• Have Set and Remove return the previous value for the key, if any.
• Have Get return the expiration time for entries.
• Add a Clear method to empty a cache.

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)
}

ExpiringCache is a cache with items that are evicted over time

Ideas for the future:

• Add an Evict method to force immediate eviction of stale items

func NewLRU

func NewLRU(defaultExpiration time.Duration, evictionInterval time.Duration, maxEntries int) 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.

type Stats

type Stats struct {
	// Writes captures the number of times state in the cache was mutated. This
	// includes setting and removing entries.
	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
}

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

The values returned in this struct are eventually consistent approximations of the current state of the cache.