Documentation ¶
Overview ¶
Package cache provides general-purpose in-memory caches. Different caches provide different eviction policies suitable for specific use cases.
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 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.