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

	// 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 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.

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.