simplecache

README

SimpleCache

A simple thread safe cache implementation using Go generics.

Why?

While many excellent cache solutions exist, what I often want for smaller projects is a map, with some expiration abilities over it. That is intended to fill that role. This is because different types can have different caching needs, such as a small group of items that should never expire, items that should exist in cache forever only being removed when the cache is full. Or some combination.

Most operations should be o(1) as well as all being thread safe.

What isn't it

1. A generic cache for anything E.G. redis/memcached
2. Aiming for extreme performance under load
3. Implementing any sort of persistence

Usage

Import github.com/boyter/simplecache

sc := simplecache.New[string]()

_ = sc.Set("key-1", "some value")

v, ok := sc.Get("key-1")
if ok {
	fmt.Println(v) // prints "some value"
}
v, ok = sc.Get("key-99")
if ok {
	fmt.Println(v) // not run "key-99" was never added
}

Note that a default cache has an limit of 100,000 items, once the next item is added beyond this limit 5 random entries will be checked, and one of them removed based on the default LFU algorithm.

You can configure this through the use of options, as indicated below

oMi := 1000
oEp := simplecache.LRU
oEs := 5
oMA := time.Second * 60

sc := simplecache.New[string](simplecache.Option{
    MaxItems:        &oMi, // max number of items the cache will hold, evicting on Set, nil for no limit
    EvictionPolicy:  &oEp, // Which eviction policy should be applied LRU or LFU
    EvictionSamples: &oEs, // How many random samples to take from the items to find the best to expire
    MaxAge:          &oMA, // Max age an item can live on Get when past this will be deleted, nil for no expiry
})

Benchmarks?

I don't have any. It's a Go map with some locking. It should be fine. Being 5% faster or slower than any other cache isn't the point here.

Documentation

Index

• Variables
• type Cache
  • func New[T any](opts ...Option) *Cache[T]
  • func (c *Cache[T]) Clear()
  • func (c *Cache[T]) Delete(key string)
  • func (c *Cache[T]) Get(key string) (T, bool)
  • func (c *Cache[T]) Set(key string, value T) error
  • func (c *Cache[T]) Sum() int
• type CacheEvictionPolicy
• type CacheInterface
• type Option

Variables

var ErrInvalidEvictionPolicy = errors.New("invalid eviction policy")

Types

type Cache

type Cache[T any] struct {
	// contains filtered or unexported fields
}

Cache is a generic cache implementation using a map not designed for raw performance but to be simple to configure

func New

func New[T any](opts ...Option) *Cache[T]

New creates and returns a new Cache

func (*Cache[T]) Clear

func (c *Cache[T]) Clear()

Clear removes all entries from the cache

func (*Cache[T]) Delete

func (c *Cache[T]) Delete(key string)

Delete removes an item from the cache by key

func (*Cache[T]) Get

func (c *Cache[T]) Get(key string) (T, bool)

Get retrieves an item from the cache by key, also incrementing the hit count

func (*Cache[T]) Set

func (c *Cache[T]) Set(key string, value T) error

Set adds or updates an item in the cache with a given key

func (*Cache[T]) Sum

func (c *Cache[T]) Sum() int

Sum returns the count of items in the cache

type CacheEvictionPolicy

type CacheEvictionPolicy int

const (
	LRU CacheEvictionPolicy = iota
	LFU
)

type CacheInterface

type CacheInterface[T any] interface {
	// Set adds or updates an item in the cache
	Set(key string, value T) error

	// Get retrieves an item from the cache by key, returning the value and a boolean indicating if the value was found
	Get(key string) (T, bool)

	// Delete removes an item from the cache by key
	Delete(key string)

	// Clear removes all items from the cache
	Clear()

	// Sum returns the count of items in the cache
	Sum() int
}

CacheInterface is an interface for the Cache type mostly for mocking purposes

type Option

type Option struct {
	MaxItems        *int
	EvictionPolicy  *CacheEvictionPolicy
	EvictionSamples *int
	MaxAge          *time.Duration
}