gocache

gocache is an easy-to-use, high-performance, lightweight and thread-safe (goroutine-safe) in-memory key-value cache with support for LRU and FIFO eviction policies as well as expiration, bulk operations and even retrieval of keys by pattern.

Table of Contents

• Features
• Usage
  • Initializing the cache
  • Functions
  • Examples
    • Creating or updating an entry
    • Getting an entry
    • Deleting an entry
    • Complex example
• Persistence
• Eviction
  • MaxSize
  • MaxMemoryUsage
• Expiration
• Performance
  • Summary
  • Results
• FAQ
  • How can I persist the data on application termination?

Features

gocache supports the following cache eviction policies:

• First in first out (FIFO)
• Least recently used (LRU)

It also supports cache entry TTL, which is both active and passive. Active expiration means that if you attempt to retrieve a cache key that has already expired, it will delete it on the spot and the behavior will be as if the cache key didn't exist. As for passive expiration, there's a background task that will take care of deleting expired keys.

It also includes what you'd expect from a cache, like GET/SET, bulk operations and get by pattern.

Usage

go get -u github.com/TwiN/gocache/v2

Initializing the cache

cache := gocache.NewCache().WithMaxSize(1000).WithEvictionPolicy(gocache.LeastRecentlyUsed)

If you're planning on using expiration (SetWithTTL or Expire) and you want expired entries to be automatically deleted in the background, make sure to start the janitor when you instantiate the cache:

cache.StartJanitor()

Functions

| Function | Description | |-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | WithMaxSize | Sets the max size of the cache. gocache.NoMaxSize means there is no limit. If not set, the default max size is gocache.DefaultMaxSize. | | WithMaxMemoryUsage | Sets the max memory usage of the cache. gocache.NoMaxMemoryUsage means there is no limit. The default behavior is to not evict based on memory usage. | | WithEvictionPolicy | Sets the eviction algorithm to be used when the cache reaches the max size. If not set, the default eviction policy is gocache.FirstInFirstOut (FIFO). | | WithDefaultTTL | Sets the default TTL for each entry. | | WithForceNilInterfaceOnNilPointer | Configures whether values with a nil pointer passed to write functions should be forcefully set to nil. Defaults to true. | | StartJanitor | Starts the janitor, which is in charge of deleting expired cache entries in the background. | | StopJanitor | Stops the janitor. | | Set | Same as SetWithTTL, but using the default TTL (which is gocache.NoExpiration, unless configured otherwise). | | SetWithTTL | Creates or updates a cache entry with the given key, value and expiration time. If the max size after the aforementioned operation is above the configured max size, the tail will be evicted. Depending on the eviction policy, the tail is defined as the oldest | | SetAll | Same as Set, but in bulk. | | SetAllWithTTL | Same as SetWithTTL, but in bulk. | | Get | Gets a cache entry by its key. | | GetByKeys | Gets a map of entries by their keys. The resulting map will contain all keys, even if some of the keys in the slice passed as parameter were not present in the cache. | | GetAll | Gets all cache entries. | | GetKeysByPattern | Retrieves a slice of keys that matches a given pattern. | | Delete | Removes a key from the cache. | | DeleteAll | Removes multiple keys from the cache. | | DeleteKeysByPattern | Removes all keys that that matches a given pattern. | | Count | Gets the size of the cache. This includes cache keys which may have already expired, but have not been removed yet. | | Clear | Wipes the cache. | | TTL | Gets the time until a cache key expires. | | Expire | Sets the expiration time of an existing cache key. |

For further documentation, please refer to Go Reference

Examples

Creating or updating