cache

README

go-generics-cache

go-generics-cache is an in-memory key:value store/cache that is suitable for applications running on a single machine. This in-memory cache uses Go Generics which will be introduced in 1.18.

• a thread-safe
• implemented with Go Generics
• TTL supported (with expiration times)
• Simple cache is like map[string]interface{}
  • See examples
• Cache replacement policies
  • Least recently used (LRU)
    • Discards the least recently used items first.
    • See examples
  • Least-frequently used (LFU)
    • Counts how often an item is needed. Those that are used least often are discarded first.
    • An O(1) algorithm for implementing the LFU cache eviction scheme
    • See examples
  • First in first out (FIFO)
    • Using this algorithm the cache behaves in the same way as a FIFO queue.
    • The cache evicts the blocks in the order they were added, without any regard to how often or how many times they were accessed before.
    • See examples
  • Most recently used (MRU)
    • In contrast to Least Recently Used (LRU), MRU discards the most recently used items first.
    • See examples
  • Clock
    • Clock is a more efficient version of FIFO than Second-chance cache algorithm.
    • See examples

Requirements

Go 1.18 or later.

If Go 1.18 has not been released but you want to try this package, you can easily do so by using the gotip command.

$ go install golang.org/dl/gotip@latest
$ gotip download # latest commit
$ gotip version
go version devel go1.18-c2397905e0 Sat Nov 13 03:33:55 2021 +0000 darwin/arm64

Install

$ go get github.com/Code-Hex/go-generics-cache

Usage

See also examples or gotipplay playground

package main

import (
	"fmt"
	"time"

	cache "github.com/Code-Hex/go-generics-cache"
)

func main() {
	// use simple cache algorithm without options.
	c := cache.New[string, int]()
	c.Set("a", 1)
	gota, aok := c.Get("a")
	gotb, bok := c.Get("b")
	fmt.Println(gota, aok) // 1 true
	fmt.Println(gotb, bok) // 0 false

	// Create a cache for Number constraint. key as string, value as int.
	nc := cache.NewNumber[string, int]()
	nc.Set("age", 26, cache.WithExpiration(time.Hour))

	incremented := nc.Increment("age", 1)
	fmt.Println(incremented) // 27

	decremented := nc.Decrement("age", 1)
	fmt.Println(decremented) // 26
}

Articles

• English: Some tips and bothers for Go 1.18 Generics
• Japanese: Go 1.18 の Generics を使ったキャッシュライブラリを作った時に見つけた tips と微妙な点

Documentation

Index

• type Cache
  • func New[K comparable, V any](opts ...Option[K, V]) *Cache[K, V]
  • func NewContext[K comparable, V any](ctx context.Context, opts ...Option[K, V]) *Cache[K, V]
  • func (c *Cache[K, V]) Contains(key K) bool
  • func (c *Cache[K, V]) Delete(key K)
  • func (c *Cache[K, V]) DeleteExpired()
  • func (c *Cache[K, V]) Get(key K) (value V, ok bool)
  • func (c *Cache[K, V]) Keys() []K
  • func (c *Cache[K, V]) Set(key K, val V, opts ...ItemOption)
• type Interface
• type Item
  • func (item *Item[K, V]) Expired() bool
• type ItemOption
  • func WithExpiration(exp time.Duration) ItemOption
• type Number
• type NumberCache
  • func NewNumber[K comparable, V Number](opts ...Option[K, V]) *NumberCache[K, V]
  • func (nc *NumberCache[K, V]) Decrement(key K, n V) V
  • func (nc *NumberCache[K, V]) Increment(key K, n V) V
• type Option
  • func AsClock[K comparable, V any](opts ...clock.Option) Option[K, V]
  • func AsFIFO[K comparable, V any](opts ...fifo.Option) Option[K, V]
  • func AsLFU[K comparable, V any](opts ...lfu.Option) Option[K, V]
  • func AsLRU[K comparable, V any](opts ...lru.Option) Option[K, V]
  • func AsMRU[K comparable, V any](opts ...mru.Option) Option[K, V]
  • func WithJanitorInterval[K comparable, V any](d time.Duration) Option[K, V]

Examples

• AsClock
• Cache
• Cache.Contains
• Cache.Delete
• Cache.Keys
• NewContext
• NewNumber
• WithExpiration

Types

type Cache

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

Cache is a thread safe cache.

Example

package main

import (
	"fmt"

	cache "github.com/Code-Hex/go-generics-cache"
)

func main() {
	// use simple cache algorithm without options.
	c := cache.New[string, int]()
	c.Set("a", 1)
	gota, aok := c.Get("a")
	gotb, bok := c.Get("b")
	fmt.Println(gota, aok)
	fmt.Println(gotb, bok)
}

Output:

1 true
0 false

func New

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

New creates a new thread safe Cache. This function will be stopped an internal janitor when the cache is no longer referenced anywhere.

There are several Cache replacement policies available with you specified any options.

func NewContext

func NewContext[K comparable, V any](ctx context.Context, opts ...Option[K, V]) *Cache[K, V]

NewContext creates a new thread safe Cache with context.

There are several Cache replacement policies available with you specified any options.

Example

package main

import (
	"context"
	"fmt"
	"time"

	cache "github.com/Code-Hex/go-generics-cache"
)

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	// use simple cache algorithm without options.
	// an internal janitor will be stopped if specified the context is cancelled.
	c := cache.NewContext(ctx, cache.WithJanitorInterval[string, int](3*time.Second))
	c.Set("a", 1)
	gota, aok := c.Get("a")
	gotb, bok := c.Get("b")
	fmt.Println(gota, aok)
	fmt.Println(gotb, bok)
}

Output:

1 true
0 false

func (*Cache[K, V]) Contains

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

Contains reports whether key is within cache.

Example

package main

import (
	"fmt"

	cache "github.com/Code-Hex/go-generics-cache"
)

func main() {
	c := cache.New(cache.AsLRU[string, int]())
	c.Set("a", 1)
	fmt.Println(c.Contains("a"))
	fmt.Println(c.Contains("b"))
}

Output:

true
false

func (*Cache[K, V]) Delete

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

Delete deletes the item with provided key from the cache.

Example

package main

import (
	"fmt"

	cache "github.com/Code-Hex/go-generics-cache"
)

func main() {
	c := cache.New(cache.AsMRU[string, int]())
	c.Set("a", 1)
	c.Delete("a")
	gota, aok := c.Get("a")
	fmt.Println(gota, aok)
}

Output:

0 false

func (*Cache[K, V]) DeleteExpired

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

DeleteExpired all expired items from the cache.

func (*Cache[K, V]) Get

func (c *Cache[K, V]) Get(key K) (value V, ok bool)

Get looks up a key's value from the cache.

func (*Cache[K, V]) Keys

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

Keys returns the keys of the cache. the order is relied on algorithms.

Example

package main

import (
	"fmt"

	cache "github.com/Code-Hex/go-generics-cache"
)

func main() {
	c := cache.New(cache.AsLFU[string, int]())
	c.Set("a", 1)
	c.Set("b", 1)
	c.Set("c", 1)
	fmt.Println(c.Keys())
}

Output:

[a b c]

func (*Cache[K, V]) Set

func (c *Cache[K, V]) Set(key K, val V, opts ...ItemOption)

Set sets a value to the cache with key. replacing any existing value.

type Interface

type Interface[K comparable, V any] interface {
	Get(key K) (value V, ok bool)
	Set(key K, val V)
	Keys() []K
	Delete(key K)
}

Interface is a common-cache interface.

type Item

type Item[K comparable, V any] struct {
	Key        K
	Value      V
	Expiration time.Time
}

Item is an item

func (*Item[K, V]) Expired

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

Expired returns true if the item has expired.

type ItemOption

type ItemOption func(*itemOptions)

ItemOption is an option for cache item.

func WithExpiration

func WithExpiration(exp time.Duration) ItemOption

WithExpiration is an option to set expiration time for any items. If the expiration is zero or negative value, it treats as w/o expiration.

Example

package main

import (
	"fmt"
	"time"

	cache "github.com/Code-Hex/go-generics-cache"
)

func main() {
	c := cache.New(cache.AsFIFO[string, int]())
	exp := 250 * time.Millisecond
	c.Set("a", 1, cache.WithExpiration(exp))

	// check item is set.
	gota, aok := c.Get("a")
	fmt.Println(gota, aok)

	// set again
	c.Set("a", 2, cache.WithExpiration(exp))
	gota2, aok2 := c.Get("a")
	fmt.Println(gota2, aok2)

	// waiting expiration.
	time.Sleep(exp + 100*time.Millisecond) // + buffer

	gota3, aok3 := c.Get("a") // expired
	fmt.Println(gota3, aok3)
}

Output:

1 true
2 true
0 false

type Number

type Number interface {
	constraints.Integer | constraints.Float | constraints.Complex
}

Number is a constraint that permits any numeric types.

type NumberCache

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

NumberCache is a in-memory cache which is able to store only Number constraint.

func NewNumber

func NewNumber[K comparable, V Number](opts ...Option[K, V]) *NumberCache[K, V]

NewNumber creates a new cache for Number constraint.

Example

package main

import (
	"fmt"
	"time"

	cache "github.com/Code-Hex/go-generics-cache"
)

func main() {
	nc := cache.NewNumber[string, int]()
	nc.Set("a", 1)
	nc.Set("b", 2, cache.WithExpiration(time.Minute))
	av := nc.Increment("a", 1)
	gota, aok := nc.Get("a")

	bv := nc.Decrement("b", 1)
	gotb, bok := nc.Get("b")

	// not set keys
	cv := nc.Increment("c", 100)
	dv := nc.Decrement("d", 100)
	fmt.Println(av, gota, aok)
	fmt.Println(bv, gotb, bok)
	fmt.Println(cv)
	fmt.Println(dv)
}

Output:

2 2 true
1 1 true
100
-100

func (*NumberCache[K, V]) Decrement

func (nc *NumberCache[K, V]) Decrement(key K, n V) V

Decrement an item of type Number constraint by n. Returns the decremented value.

func (*NumberCache[K, V]) Increment

func (nc *NumberCache[K, V]) Increment(key K, n V) V

Increment an item of type Number constraint by n. Returns the incremented value.

type Option

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

Option is an option for cache.

func AsClock

func AsClock[K comparable, V any](opts ...clock.Option) Option[K, V]

AsClock is an option to make a new Cache as clock algorithm.

Example

package main

import (
	"fmt"

	cache "github.com/Code-Hex/go-generics-cache"
)

func main() {
	// use clock cache algorithm.
	c := cache.New(cache.AsClock[string, int]())
	c.Set("a", 1)
	gota, aok := c.Get("a")
	gotb, bok := c.Get("b")
	fmt.Println(gota, aok)
	fmt.Println(gotb, bok)
}

Output:

1 true
0 false

func AsFIFO

func AsFIFO[K comparable, V any](opts ...fifo.Option) Option[K, V]

AsFIFO is an option to make a new Cache as FIFO algorithm.

func AsLFU

func AsLFU[K comparable, V any](opts ...lfu.Option) Option[K, V]

AsLFU is an option to make a new Cache as LFU algorithm.

func AsLRU

func AsLRU[K comparable, V any](opts ...lru.Option) Option[K, V]

AsLRU is an option to make a new Cache as LRU algorithm.

func AsMRU

func AsMRU[K comparable, V any](opts ...mru.Option) Option[K, V]

AsMRU is an option to make a new Cache as MRU algorithm.

func WithJanitorInterval

func WithJanitorInterval[K comparable, V any](d time.Duration) Option[K, V]

WithJanitorInterval is an option to specify how often cache should delete expired items.

Default is 1 minute.