cache

README

GO-CACHE

High performance, simple generic cache written in GO, including a loading cache.

🚀 Install

go get github.com/larscom/go-cache

💡 Usage

You can import go-cache using:

import (
    "github.com/larscom/go-cache"
)

🫱 Loading cache

Create a new loading cache with int type as key and string type as value.

A common use case for this loading cache would be to automatically fetch data from a REST API and store it in cache. This implementation will ensure that the REST API is only called once in a concurrent environment.

func main() {
  	loaderFunc := func(key int) (string, error) {
         // you may want to call your REST API here...
         return "Hello World", nil
	  }

    c := cache.NewLoadingCache[int, string](loaderFunc)
    defer c.Close()

    value, err := c.Load(1)
    if err != nil {
      log.Fatal(err)
    }
    log.Println(value) // Hello World
}

With TTL option

Create a new loading cache with time to live of 10 seconds.

This allows you to call Load() as many times as you want and whenever an entry expires it'll call the loaderFunc once.

func main() {
    c := cache.NewLoadingCache(loaderFunc, cache.WithExpireAfterWrite[int, string](time.Second * 10))
    defer c.Close()
}

🫱 Cache

Create a regular cache (without Load and Reload functions) with TTL

func main() {
    c := cache.NewCache[int, string](cache.WithExpireAfterWrite[int, string](time.Second * 10))
    defer c.Close()

    c.Put(1, "Hello World")

    value, found := c.Get(1)
    if found {
       log.Println(value) // Hello World
    }
}

Documentation

Index

• func NoopLoaderFunc[K comparable, V any](key K) (V, error)
• type Cache
  • func NewCache[K comparable, V any](options ...Option[K, V]) Cache[K, V]
• type LoaderFunc
• type LoadingCache
  • func NewLoadingCache[K comparable, V any](loaderFunc LoaderFunc[K, V], options ...Option[K, V]) LoadingCache[K, V]
• type Option
  • func WithExpireAfterWrite[K comparable, V any](expireAfterWrite time.Duration) Option[K, V]

Functions

func NoopLoaderFunc

func NoopLoaderFunc[K comparable, V any](key K) (V, error)

Function that can be used inside a testing environment

Types

type Cache

type Cache[K comparable, V any] interface {
	// Get an item from the cache.
	Get(key K) (V, bool)

	// Put an item into cache.
	Put(key K, value V)

	// Returns true when the item exist in cache.
	Has(key K) bool

	// Returns true if the cache is empty.
	IsEmpty() bool

	// Returns the total count of cached items.
	Count() int

	// Loop over each entry in the cache.
	ForEach(func(key K, value V))

	// Deletes an item from the cache.
	Delete(key K)

	// Clear all items from cache.
	Clear()

	// Cleanup resources and timers.
	Close()
}

func NewCache

func NewCache[K comparable, V any](
	options ...Option[K, V],
) Cache[K, V]

type LoaderFunc

type LoaderFunc[K comparable, V any] func(key K) (V, error)

Function that gets executed by the 'Load' and 'Reload' function

type LoadingCache

type LoadingCache[K comparable, V any] interface {
	// Loads an item into cache using the provided LoaderFunc and returns the value.
	//
	// If the item is already cached, it'll return that value instead.
	//
	// Whenever the LoaderFunc returns an error, the value does NOT get saved.
	//
	// This function is thread-safe and the LoaderFunc is called only once in a concurrent environment.
	Load(key K) (V, error)

	// Reloads an item into cache using the provided LoaderFunc and returns the new value.
	//
	// Whenever the LoaderFunc returns an error, the value does NOT get saved (old value remains in cache)
	Reload(key K) (V, error)

	// Embed Cache
	Cache[K, V]
}

func NewLoadingCache

func NewLoadingCache[K comparable, V any](
	loaderFunc LoaderFunc[K, V],
	options ...Option[K, V],
) LoadingCache[K, V]

type Option

type Option[K comparable, V any] func(c *cache[K, V])

func WithExpireAfterWrite

func WithExpireAfterWrite[K comparable, V any](
	expireAfterWrite time.Duration,
) Option[K, V]

The 'TTL' after it has been written to the cache.