ttlcache

README

TTLCache - an in-memory cache with item expiration and generics

Features

• Simple API
• Type parameters
• Item expiration and automatic deletion
• Automatic expiration time extension on each Get call
• Loader interface that may be used to load/lazily initialize missing cache
• Thread Safe items
• Event handlers (insertion and eviction)
• Metrics

Installation

go get github.com/jellydator/ttlcache/v3

Usage

The main type of ttlcache is Cache. It represents a single in-memory data store.

To create a new instance of ttlcache.Cache, the ttlcache.New() function should be called:

func main() {
	cache := ttlcache.New[string, string]()
}

Note that by default, a new cache instance does not let any of its items to expire or be automatically deleted. However, this feature can be activated by passing a few additional options into the ttlcache.New() function and calling the cache.Start() method:

func main() {
	cache := ttlcache.New[string, string](
		ttlcache.WithTTL[string, string](30 * time.Minute),
	)

	go cache.Start() // starts automatic expired item deletion
}

Even though the cache.Start() method handles expired item deletion well, there may be times when the system that uses ttlcache needs to determine when to delete the expired items itself. For example, it may need to delete them only when the resource load is at its lowest (e.g., after midnight, when the number of users/HTTP requests drops). So, in situations like these, instead of calling cache.Start(), the system could periodically call cache.DeleteExpired():

func main() {
	cache := ttlcache.New[string, string](
		ttlcache.WithTTL[string, string](30 * time.Minute),
	)

	for {
		time.Sleep(4 * time.Hour)
		cache.DeleteExpired()
	}
}

The data stored in ttlcache.Cache can be retrieved, checked and updated with Set, Get, Delete, Has etc. methods:

func main() {
	cache := ttlcache.New[string, string](
		ttlcache.WithTTL[string, string](30 * time.Minute),
	)

	// insert data
	cache.Set("first", "value1", ttlcache.DefaultTTL)
	cache.Set("second", "value2", ttlcache.NoTTL)
	cache.Set("third", "value3", ttlcache.DefaultTTL)

	// retrieve data
	item := cache.Get("first")
	fmt.Println(item.Value(), item.ExpiresAt())

	// check key 
	ok := cache.Has("third")
	
	// delete data
	cache.Delete("second")
	cache.DeleteExpired()
	cache.DeleteAll()

	// retrieve data if in cache otherwise insert data
	item, retrieved := cache.GetOrSet("fourth", "value4", WithTTL[string, string](ttlcache.DefaultTTL))

	// retrieve and delete data
	item, present := cache.GetAndDelete("fourth")
}

To subscribe to insertion and eviction events, cache.OnInsertion() and cache.OnEviction() methods should be used:

func main() {
	cache := ttlcache.New[string, string](
		ttlcache.WithTTL[string, string](30 * time.Minute),
		ttlcache.WithCapacity[string, string](300),
	)

	cache.OnInsertion(func(ctx context.Context, item *ttlcache.Item[string, string]) {
		fmt.Println(item.Value(), item.ExpiresAt())
	})
	cache.OnEviction(func(ctx context.Context, reason ttlcache.EvictionReason, item *ttlcache.Item[string, string]) {
		if reason == ttlcache.EvictionReasonCapacityReached {
			fmt.Println(item.Key(), item.Value())
		}
	})

	cache.Set("first", "value1", ttlcache.DefaultTTL)
	cache.DeleteAll()
}

To load data when the cache does not have it, a custom or existing implementation of ttlcache.Loader can be used:

func main() {
	loader := ttlcache.LoaderFunc[string, string](
		func(c *ttlcache.Cache[string, string], key string) *ttlcache.Item[string, string] {
			// load from file/make an HTTP request
			item := c.Set("key from file", "value from file")
			return item
		},
	)
	cache := ttlcache.New[string, string](
		ttlcache.WithLoader[string, string](loader),
	)

	item := cache.Get("key from file")
}

Documentation

Index

• Constants
• type Cache
  • func New[K comparable, V any](opts ...Option[K, V]) *Cache[K, V]
  • func (c *Cache[K, V]) Delete(key K)
  • func (c *Cache[K, V]) DeleteAll()
  • func (c *Cache[K, V]) DeleteExpired()
  • func (c *Cache[K, V]) Get(key K, opts ...Option[K, V]) *Item[K, V]
  • func (c *Cache[K, V]) GetAndDelete(key K, opts ...Option[K, V]) (*Item[K, V], bool)
  • func (c *Cache[K, V]) GetOrSet(key K, value V, opts ...Option[K, V]) (*Item[K, V], bool)
  • func (c *Cache[K, V]) Has(key K) bool
  • func (c *Cache[K, V]) Items() map[K]*Item[K, V]
  • func (c *Cache[K, V]) Keys() []K
  • func (c *Cache[K, V]) Len() int
  • func (c *Cache[K, V]) Metrics() Metrics
  • func (c *Cache[K, V]) OnEviction(fn func(context.Context, EvictionReason, *Item[K, V])) func()
  • func (c *Cache[K, V]) OnInsertion(fn func(context.Context, *Item[K, V])) func()
  • func (c *Cache[K, V]) Range(fn func(item *Item[K, V]) bool)
  • func (c *Cache[K, V]) RangeBackwards(fn func(item *Item[K, V]) bool)
  • func (c *Cache[K, V]) Set(key K, value V, ttl time.Duration) *Item[K, V]
  • func (c *Cache[K, V]) Start()
  • func (c *Cache[K, V]) Stop()
  • func (c *Cache[K, V]) Touch(key K)
• type EvictionReason
• type Item
  • func (item *Item[K, V]) ExpiresAt() time.Time
  • func (item *Item[K, V]) IsExpired() bool
  • func (item *Item[K, V]) Key() K
  • func (item *Item[K, V]) TTL() time.Duration
  • func (item *Item[K, V]) Value() V
  • func (item *Item[K, V]) Version() int64
• type Loader
• type LoaderFunc
  • func (l LoaderFunc[K, V]) Load(c *Cache[K, V], key K) *Item[K, V]
• type Metrics
• type Option
  • func WithCapacity[K comparable, V any](c uint64) Option[K, V]
  • func WithDisableTouchOnHit[K comparable, V any]() Option[K, V]
  • func WithLoader[K comparable, V any](l Loader[K, V]) Option[K, V]
  • func WithTTL[K comparable, V any](ttl time.Duration) Option[K, V]
  • func WithVersion[K comparable, V any](enable bool) Option[K, V]
• type SuppressedLoader
  • func NewSuppressedLoader[K comparable, V any](loader Loader[K, V], group *singleflight.Group) *SuppressedLoader[K, V]
  • func (l *SuppressedLoader[K, V]) Load(c *Cache[K, V], key K) *Item[K, V]

Constants

const (
	// NoTTL indicates that an item should never expire.
	NoTTL time.Duration = -1

	// PreviousOrDefaultTTL indicates that existing TTL of item should be used
	// default TTL will be used as fallback if item doesn't exist
	PreviousOrDefaultTTL time.Duration = -2

	// DefaultTTL indicates that the default TTL value of the cache
	// instance should be used.
	DefaultTTL time.Duration = 0
)

Types

type Cache

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

Cache is a synchronised map of items that are automatically removed when they expire or the capacity is reached.

func New

func New[K comparable, V any](opts ...Option[K, V]) *Cache[K, V]

New creates a new instance of cache.

func (*Cache[K, V]) Delete

func (c *Cache[K, V]) Delete(key K)

Delete deletes an item from the cache. If the item associated with the key is not found, the method is no-op.

func (*Cache[K, V]) DeleteAll

func (c *Cache[K, V]) DeleteAll()

DeleteAll deletes all items from the cache.

func (*Cache[K, V]) DeleteExpired

func (c *Cache[K, V]) DeleteExpired()

DeleteExpired deletes all expired items from the cache.

func (*Cache[K, V]) Get

func (c *Cache[K, V]) Get(key K, opts ...Option[K, V]) *Item[K, V]

Get retrieves an item from the cache by the provided key. Unless this is disabled, it also extends/touches an item's expiration timestamp on successful retrieval. If the item is not found, a nil value is returned.

func (*Cache[K, V]) GetAndDelete

func (c *Cache[K, V]) GetAndDelete(key K, opts ...Option[K, V]) (*Item[K, V], bool)

GetAndDelete retrieves an item from the cache by the provided key and then deletes it. The bool return value is true if the item was found before its deletion, false if not. If the loader is non-nil (i.e., used as an option or specified when creating the cache instance), it is executed normaly, i.e., only when the item is not found.

func (*Cache[K, V]) GetOrSet

func (c *Cache[K, V]) GetOrSet(key K, value V, opts ...Option[K, V]) (*Item[K, V], bool)

GetOrSet retrieves an item from the cache by the provided key. If the item is not found, it is created with the provided options and then returned. The bool return value is true if the item was found, false if created during the execution of the method. If the loader is non-nil (i.e., used as an option or specified when creating the cache instance), its execution is skipped.

func (*Cache[K, V]) Has

func (c *Cache[K, V]) Has(key K) bool

Has checks whether the key exists in the cache.

func (*Cache[K, V]) Items

func (c *Cache[K, V]) Items() map[K]*Item[K, V]

Items returns a copy of all items in the cache. It does not update any expiration timestamps.

func (*Cache[K, V]) Keys

func (c *Cache[K, V]) Keys() []K

Keys returns all unexpired keys in the cache.

func (*Cache[K, V]) Len

func (c *Cache[K, V]) Len() int

Len returns the number of unexpired items in the cache.

func (*Cache[K, V]) Metrics

func (c *Cache[K, V]) Metrics() Metrics

Metrics returns the metrics of the cache.

func (*Cache[K, V]) OnEviction

func (c *Cache[K, V]) OnEviction(fn func(context.Context, EvictionReason, *Item[K, V])) func()

OnEviction adds the provided function to be executed when an item is evicted/deleted from the cache. The function is executed on a separate goroutine and does not block the flow of the cache manager. The returned function may be called to delete the subscription function from the list of eviction subscribers. When the returned function is called, it blocks until all instances of the same subscription function return. A context is used to notify the subscription function when the returned/deletion function is called.

func (*Cache[K, V]) OnInsertion

func (c *Cache[K, V]) OnInsertion(fn func(context.Context, *Item[K, V])) func()

OnInsertion adds the provided function to be executed when a new item is inserted into the cache. The function is executed on a separate goroutine and does not block the flow of the cache manager. The returned function may be called to delete the subscription function from the list of insertion subscribers. When the returned function is called, it blocks until all instances of the same subscription function return. A context is used to notify the subscription function when the returned/deletion function is called.

func (*Cache[K, V]) Range

func (c *Cache[K, V]) Range(fn func(item *Item[K, V]) bool)

Range calls fn for each unexpired item in the cache. If fn returns false, Range stops the iteration.

func (*Cache[K, V]) RangeBackwards

func (c *Cache[K, V]) RangeBackwards(fn func(item *Item[K, V]) bool)

RangeBackwards calls fn for each unexpired item in the cache in reverse order. If fn returns false, RangeBackwards stops the iteration.

func (*Cache[K, V]) Set

func (c *Cache[K, V]) Set(key K, value V, ttl time.Duration) *Item[K, V]

Set creates a new item from the provided key and value, adds it to the cache and then returns it. If an item associated with the provided key already exists, the new item overwrites the existing one. NoTTL constant or -1 can be used to indicate that the item should never expire. DefaultTTL constant or 0 can be used to indicate that the item should use the default/global TTL that was specified when the cache instance was created.

func (*Cache[K, V]) Start

func (c *Cache[K, V]) Start()

Start starts an automatic cleanup process that periodically deletes expired items. It blocks until Stop is called.

func (*Cache[K, V]) Stop

func (c *Cache[K, V]) Stop()

Stop stops the automatic cleanup process. It blocks until the cleanup process exits.

func (*Cache[K, V]) Touch

func (c *Cache[K, V]) Touch(key K)

Touch simulates an item's retrieval without actually returning it. Its main purpose is to extend an item's expiration timestamp. If the item is not found, the method is no-op.

type EvictionReason

type EvictionReason int

EvictionReason is used to specify why a certain item was evicted/deleted.

const (
	EvictionReasonDeleted EvictionReason = iota + 1
	EvictionReasonCapacityReached
	EvictionReasonExpired
)

Available eviction reasons.

type Item

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

Item holds all the information that is associated with a single cache value.

func (*Item[K, V]) ExpiresAt

func (item *Item[K, V]) ExpiresAt() time.Time

ExpiresAt returns the expiration timestamp of the item.

func (*Item[K, V]) IsExpired

func (item *Item[K, V]) IsExpired() bool

IsExpired returns a bool value that indicates whether the item is expired.

func (*Item[K, V]) Key

func (item *Item[K, V]) Key() K

Key returns the key of the item.

func (*Item[K, V]) TTL

func (item *Item[K, V]) TTL() time.Duration

TTL returns the TTL value of the item.

func (*Item[K, V]) Value

func (item *Item[K, V]) Value() V

Value returns the value of the item.

func (*Item[K, V]) Version

func (item *Item[K, V]) Version() int64

Version returns the version of the item. It shows the total number of changes made to the item. If version tracking is disabled, the return value is always -1.

type Loader

type Loader[K comparable, V any] interface {
	// Load should execute a custom item retrieval logic and
	// return the item that is associated with the key.
	// It should return nil if the item is not found/valid.
	// The method is allowed to fetch data from the cache instance
	// or update it for future use.
	Load(c *Cache[K, V], key K) *Item[K, V]
}

Loader is an interface that handles missing data loading.

type LoaderFunc

type LoaderFunc[K comparable, V any] func(*Cache[K, V], K) *Item[K, V]

LoaderFunc type is an adapter that allows the use of ordinary functions as data loaders.

func (LoaderFunc[K, V]) Load

func (l LoaderFunc[K, V]) Load(c *Cache[K, V], key K) *Item[K, V]

Load executes a custom item retrieval logic and returns the item that is associated with the key. It returns nil if the item is not found/valid.

type Metrics

type Metrics struct {
	// Insertions specifies how many items were inserted.
	Insertions uint64

	// Hits specifies how many items were successfully retrieved
	// from the cache.
	// Retrievals made with a loader function are not tracked.
	Hits uint64

	// Misses specifies how many items were not found in the cache.
	// Retrievals made with a loader function are considered misses as
	// well.
	Misses uint64

	// Evictions specifies how many items were removed from the
	// cache.
	Evictions uint64
}

Metrics contains common cache metrics calculated over the course of the cache's lifetime.

type Option

type Option[K comparable, V any] interface {
	// contains filtered or unexported methods
}

Option sets a specific cache option.

func WithCapacity

func WithCapacity[K comparable, V any](c uint64) Option[K, V]

WithCapacity sets the maximum capacity of the cache. It has no effect when used with Get().

func WithDisableTouchOnHit

func WithDisableTouchOnHit[K comparable, V any]() Option[K, V]

WithDisableTouchOnHit prevents the cache instance from extending/touching an item's expiration timestamp when it is being retrieved. When used with Get(), it overrides the default value of the cache.

func WithLoader

func WithLoader[K comparable, V any](l Loader[K, V]) Option[K, V]

WithLoader sets the loader of the cache. When passing into Get(), it sets an ephemeral loader that is used instead of the cache's default one.

func WithTTL

func WithTTL[K comparable, V any](ttl time.Duration) Option[K, V]

WithTTL sets the TTL of the cache. It has no effect when used with Get().

func WithVersion

func WithVersion[K comparable, V any](enable bool) Option[K, V]

WithVersion activates item version tracking. If version tracking is disabled, the version is always -1. It has no effect when used with Get().

type SuppressedLoader

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

SuppressedLoader wraps another Loader and suppresses duplicate calls to its Load method.

func NewSuppressedLoader

func NewSuppressedLoader[K comparable, V any](loader Loader[K, V], group *singleflight.Group) *SuppressedLoader[K, V]

NewSuppressedLoader creates a new instance of suppressed loader. If the group parameter is nil, a newly created instance of *singleflight.Group is used.

func (*SuppressedLoader[K, V]) Load

func (l *SuppressedLoader[K, V]) Load(c *Cache[K, V], key K) *Item[K, V]

Load executes a custom item retrieval logic and returns the item that is associated with the key. It returns nil if the item is not found/valid. It also ensures that only one execution of the wrapped Loader's Load method is in-flight for a given key at a time.