cache

README

go-cache

Overview

Package cache implements a simple LRU cache with generics.

It provides a mechanism for caching resources that are time consuming to create or retrieve. The main feature is that the creation process runs only once even when multiple go-routines concurrently request for a key that does not exist in the cache.

Originally implemented for a small web program that dynamically generates images based on the requested URI.

Usage

import (
	"fmt"
	"sync"
	"time"

	"github.com/tunabay/go-cache"
)

type MyResource struct {
	data string
}

func CreateResource(key string) (*MyResource, time.Time, error) {
	time.Sleep(time.Second >> 2) // slow creation
	return &MyResource{data: "data " + key}, time.Time{}, nil
}

func main() {
	myCache := cache.New[string, *MyResource](CreateResource)

	showResource := func(key string) {
		val, cached, _, err := myCache.Get(key)
		if err != nil {
			panic(err)
		}
		var tag string
		if cached {
			tag = " (cached)"
		}
		fmt.Printf("%s -> %q%s\n", key, val.data, tag)
	}

	var wg sync.WaitGroup
	for i := 0; i < 12; i++ {
		wg.Add(1)
		go func(n int) {
			defer wg.Done()
			key := fmt.Sprintf("key-%d", n&3)
			showResource(key)
		}(i)
	}
	wg.Wait()
}

Run in Go Playground

Documentation and more examples

• Read the documentation.

License

go-cache is available under the MIT license. See the LICENSE file for more information.

Documentation

Overview

Package cache implements a simple LRU cache with generics.

Example (Simple)

// function to create a resource
createResource := func(key uint8) (string, time.Time, error) {
	time.Sleep(time.Second >> 2) // slow creation
	return fmt.Sprintf("resource %d", key), time.Time{}, nil
}

// cache with uint8 key and string value
myCache := cache.New[uint8, string](createResource)

var wg sync.WaitGroup
for i := 0; i < 12; i++ {
	wg.Add(1)
	go func(n int) {
		defer wg.Done()

		key := uint8(n & 0b11)
		val, cached, _, err := myCache.Get(key)
		if err != nil {
			panic(err)
		}
		var tag string
		if cached {
			tag = " (cached)"
		}
		fmt.Printf("%d -> %q%s\n", key, val, tag)
	}(i)
}
wg.Wait()

Output:

0 -> "resource 0"
1 -> "resource 1"
2 -> "resource 2"
3 -> "resource 3"
0 -> "resource 0" (cached)
1 -> "resource 1" (cached)
2 -> "resource 2" (cached)
3 -> "resource 3" (cached)
0 -> "resource 0" (cached)
1 -> "resource 1" (cached)
2 -> "resource 2" (cached)
3 -> "resource 3" (cached)

Example (Struct)

type myResource struct{ data string }

createResource := func(key string) (*myResource, time.Time, error) {
	time.Sleep(time.Second >> 2) // slow creation
	return &myResource{data: "resource " + key}, time.Time{}, nil
}

// cache with string key and *myResource value
myCache := cache.New[string, *myResource](createResource)

var wg sync.WaitGroup
for i := 0; i < 12; i++ {
	wg.Add(1)
	go func(n int) {
		defer wg.Done()

		key := fmt.Sprintf("key-%d", n&0b11)
		val, cached, _, err := myCache.Get(key)
		if err != nil {
			panic(err)
		}
		var tag string
		if cached {
			tag = " (cached)"
		}
		fmt.Printf("%s -> %q%s\n", key, val.data, tag)
	}(i)
}
wg.Wait()

Output:

key-0 -> "resource key-0"
key-1 -> "resource key-1"
key-2 -> "resource key-2"
key-3 -> "resource key-3"
key-0 -> "resource key-0" (cached)
key-1 -> "resource key-1" (cached)
key-2 -> "resource key-2" (cached)
key-3 -> "resource key-3" (cached)
key-0 -> "resource key-0" (cached)
key-1 -> "resource key-1" (cached)
key-2 -> "resource key-2" (cached)
key-3 -> "resource key-3" (cached)

Index

• type Cache
  • func New[K comparable, V any](create CreateFunc[K, V]) *Cache[K, V]
  • func NewWithConfig[K comparable, V any](conf *Config[K, V]) *Cache[K, V]
  • func (c *Cache[K, V]) CheckAndExpire()
  • func (c *Cache[K, V]) Get(key K) (V, bool, time.Time, error)
• type Config
• type CreateFunc
• type CreationError
  • func (e CreationError[_]) Error() string
  • func (e CreationError[_]) Unwrap() error
• type RemoveFunc

Examples

• Package (Simple)
• Package (Struct)

Types

type Cache

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

Cache is a simple LRU cache implementation for cacheable object creation.

func New

func New[K comparable, V any](create CreateFunc[K, V]) *Cache[K, V]

New creates a Cache with the creation func create. It uses the default configuration with MaxItems = 1024. To specify other configuration, use NewWithConfig instead.

func NewWithConfig

func NewWithConfig[K comparable, V any](conf *Config[K, V]) *Cache[K, V]

NewWithConfig creates a Cache with specified configuration.

func (*Cache[K, V]) CheckAndExpire

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

CheckAndExpire checks all the items in the cache and removes expired items. If only MaxItems is used and MaxAge or deadline is not used, calling this method has no effect. If MaxAge or the second return value of CreateFunc is used, it is better to call this method periodically to remove expired cache items.

func (*Cache[K, V]) Get

func (c *Cache[K, V]) Get(key K) (V, bool, time.Time, error)

Get gets the value for the key from the cache. If it does not exist in the cache, call CreateFunc to create the new value. It returns the value, cached or not, the cache expiration time. Note that the cache expiration time 0 represents that it never expired, not uncachable.

type Config

type Config[K comparable, V any] struct {
	// CreateFunc is the function to create a new cacheable object. It is
	// called when Get is called for a key that does not exist in the cache.
	CreateFunc CreateFunc[K, V]

	// RemoveFunc is the optional function that is called immediately after
	// a cache entry is removed from the cache.
	RemoveFunc RemoveFunc[K, V]

	// MaxItems is the maximum number of items that the cache can hold.
	// 0 indicates unlimited.
	MaxItems int

	// MaxAge is the maximum time since an item was created and cached.
	// 0 indicates unlimited.
	MaxAge time.Duration
}

Config is the config parameer set which is passed to NewWithConfig.

type CreateFunc

type CreateFunc[K comparable, V any] func(K) (V, time.Time, error)

CreateFunc represents a function for object creation. It will be called when Get is called for a key that does not exist in the cache. It should return the created value and optionally a deadline. Use time.Time{} as deadline when no deadline is specified.

type CreationError

type CreationError[K comparable] struct {
	Key K
	Err error
}

CreationError is the error type thrown when the object creation is failed.

func (CreationError[_]) Error

func (e CreationError[_]) Error() string

Error implements the error interface.

func (CreationError[_]) Unwrap

func (e CreationError[_]) Unwrap() error

Unwrap returns the underlying error of CreationError.

type RemoveFunc

type RemoveFunc[K comparable, V any] func(K, V)

RemoveFunc represents a function to be called when an item is removed from the cache. It can be used to free resources such as files held by the value. This is called inside locks, so it is recommended to return immediately. It's better to start a go routine to process with files or databases. Note that if Get is called for the same key immediately after removal, a new value for the same key may be concurrently created and cached.