incache

README

In app Cache

Incache is a minimal in-app cache package. It uses github.com/hashicorp/golang-lru/v2 for the underlying LRU and storage.

It implements a way of doing preemptive updates of the cache. The trigger for the preemptive update is based on the threshold window which is provided as a configuration. Threshold window is the duration in which the cache is about to expire at the time of fetching the value. A debounced update is initiated when a key is fetched within its threshold window.

|_____________________ _____threshold____ ________|
0min                   9mins              10mins
set key here              fetch key       key expires

Consider a cache expiry of 10 minutes, and a threshold window of 1 minute. In the timeline above, we set the cache at 0min, and 10mins is when the cache is set to expire. If you try to Get a key between 9mins & 10mins, then it is within the threshold window. At this point, it would initiate a cache update preemptively, assuming this key would be accessed again. Thereby maintaining the freshness of the data in the cache.

In a highly concurrent environment, preemptive and controlled updates help significantly reduce the number of I/O calls to the respective database, without compromising the freshness of cache. If not for a preemptive update, the application would have called the underlying database N times where N is the number of concurrent requests (e.g. in a web application), untill the cache is updated locally. This would also increase the pressure on the application to handle the concurrent reads and writes for the same key within the app cache.

Documentation

Overview

Package cache implements an in-memory, LRU cache, with preemptive update feature.

Index

• Variables
• type Cache
  • func New[K comparable, T any](cfg Config[K, T]) (*Cache[K, T], error)
  • func (ch *Cache[K, T]) Add(key K, value T) (evicted bool)
  • func (ch *Cache[K, T]) BulkAdd(tuples []Tuple[K, T]) (evicted []bool)
  • func (ch *Cache[K, T]) Get(key K) Value[T]
• type Config
  • func (cfg *Config[K, T]) Sanitize()
  • func (cfg *Config[K, T]) SanitizeValidate() error
  • func (cfg *Config[K, T]) Validate() error
• type ErrOnUpdate
• type Payload
• type Tuple
• type Value

Variables

var (
	ErrValidation = errors.New("invalid")
)

Types

type Cache

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

func New

func New[K comparable, T any](cfg Config[K, T]) (*Cache[K, T], error)

func (*Cache[K, T]) Add

func (ch *Cache[K, T]) Add(key K, value T) (evicted bool)

func (*Cache[K, T]) BulkAdd

func (ch *Cache[K, T]) BulkAdd(tuples []Tuple[K, T]) (evicted []bool)

func (*Cache[K, T]) Get

func (ch *Cache[K, T]) Get(key K) Value[T]

type Config

type Config[K comparable, T any] struct {
	// LRUCacheSize is the number of keys to be maintained in the cache
	LRUCacheSize uint
	// QLength is the length of update and delete queue
	QLength uint

	// CacheAge is for how long the cache would be maintained, apart from the LRU eviction
	// It's maintained to not maintain stale data if/when keys are not evicted based on LRU
	CacheAge time.Duration
	// Threshold is the duration prior to expiry, when the key is considered eligible to be updated
	Threshold    time.Duration
	DisableCache bool

	// ServeStale will not return error if the cache has expired. It will return the stale
	// value, and trigger an update as well. This is useful for usecases where it's ok
	// to serve stale values and data consistency is not of paramount importance
	ServeStale bool

	// UpdaterTimeout is the context time out for when the updater function is called
	UpdaterTimeout time.Duration
	Updater        updater[K, T]
	// ErrWatcher is called when there's any error when trying to update cache
	ErrWatcher ErrOnUpdate
}

func (*Config[K, T]) Sanitize

func (cfg *Config[K, T]) Sanitize()

func (*Config[K, T]) SanitizeValidate

func (cfg *Config[K, T]) SanitizeValidate() error

func (*Config[K, T]) Validate

func (cfg *Config[K, T]) Validate() error

type ErrOnUpdate

type ErrOnUpdate func(err error)

type Payload

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

type Tuple

type Tuple[K comparable, T any] struct {
	Key   K
	Value T
}

type Value

type Value[T any] struct {
	V     T
	Found bool
}