cache

README

go-cache

Modified from https://github.com/fanjindong/go-cache with Generics in Go 1.18+.

Install

go get -u github.com/Xhofe/go-cache

Basic Usage

import "github.com/Xhofe/go-cache"

func main() {
    c := cache.NewMemCache[int]()
    c.Set("a", 1)
    c.Set("b", 1, cache.WithEx[int](1*time.Second))
    time.sleep(1*time.Second)
    c.Get("a") // 1, true
    c.Get("b") // nil, false
}

Documentation

Index

• type Config
  • func NewConfig[V any]() *Config[V]
• type ExpiredCallback
• type ICache
  • func NewMemCache[V any](opts ...ICacheOption[V]) ICache[V]
• type ICacheOption
  • func WithClearInterval[V any](d time.Duration) ICacheOption[V]
  • func WithExpiredCallback[V any](ec ExpiredCallback[V]) ICacheOption[V]
  • func WithHash[V any](hash IHash) ICacheOption[V]
  • func WithShards[V any](shards int) ICacheOption[V]
• type IHash
• type IItem
• type Item
  • func (i *Item[V]) CanExpire() bool
  • func (i *Item[V]) Expired() bool
  • func (i *Item[V]) SetExpireAt(t time.Time)
• type MemCache
  • func (c MemCache) Clear()
  • func (c MemCache) Del(ks ...string) int
  • func (c MemCache) DelExpired(k string) bool
  • func (c MemCache) Exists(ks ...string) bool
  • func (c MemCache) Expire(k string, d time.Duration) bool
  • func (c MemCache) ExpireAt(k string, t time.Time) bool
  • func (c MemCache) Get(k string) (V, bool)
  • func (c MemCache) GetDel(k string) (V, bool)
  • func (c MemCache) GetSet(k string, v V, opts ...SetIOption[V]) (V, bool)
  • func (c MemCache) Persist(k string) bool
  • func (c MemCache) Set(k string, v V, opts ...SetIOption[V]) bool
  • func (c MemCache) Ttl(k string) (time.Duration, bool)
• type SetIOption
  • func WithEx[V any](d time.Duration) SetIOption[V]
  • func WithExAt[V any](t time.Time) SetIOption[V]

Types

type Config

type Config[V any] struct {
	// contains filtered or unexported fields
}

func NewConfig

func NewConfig[V any]() *Config[V]

type ExpiredCallback

type ExpiredCallback[V any] func(k string, v V) error

ExpiredCallback Callback the function when the key-value pair expires Note that it is executed after expiration

type ICache

type ICache[T any] interface {
	//Set key to hold the string value. If key already holds a value, it is overwritten, regardless of its type.
	//Any previous time to live associated with the key is discarded on successful SET operation.
	//Example:
	//c.Set("demo", 1)
	//c.Set("demo", 1, WithEx[int](10*time.Second))
	//c.Set("demo", 1, WithEx[int](10*time.Second), WithNx[int]())
	Set(k string, v T, opts ...SetIOption[T]) bool
	//Get the value of key.
	//If the key does not exist the special value nil,false is returned.
	//Example:
	//c.Get("demo") //nil, false
	//c.Set("demo", "value")
	//c.Get("demo") //"value", true
	Get(k string) (T, bool)
	//GetSet Atomically sets key to value and returns the old value stored at key.
	//Returns nil,false when key not exists.
	//Example:
	//c.GetSet("demo", 1) //nil,false
	//c.GetSet("demo", 2) //1,true
	GetSet(k string, v T, opts ...SetIOption[T]) (T, bool)
	//GetDel Get the value of key and delete the key.
	//This command is similar to GET, except for the fact that it also deletes the key on success.
	//Example:
	//c.Set("demo", "value")
	//c.GetDel("demo") //"value", true
	//c.GetDel("demo") //nil, false
	GetDel(k string) (T, bool)
	//Del Removes the specified keys. A key is ignored if it does not exist.
	//Return the number of keys that were removed.
	//Example:
	//c.Set("demo1", "1")
	//c.Set("demo2", "1")
	//c.Del("demo1", "demo2", "demo3") //2
	Del(keys ...string) int
	//DelExpired Only delete when key expires
	//Example:
	//c.Set("demo1", "1")
	//c.Set("demo2", "1", WithEx[string](1*time.Second))
	//time.Sleep(1*time.Second)
	//c.DelExpired("demo1", "demo2") //true
	DelExpired(k string) bool
	//Exists Returns if key exists.
	//Return the number of exists keys.
	//Example:
	//c.Set("demo1", "1")
	//c.Set("demo2", "1")
	//c.Exists("demo1", "demo2", "demo3") //2
	Exists(keys ...string) bool
	//Expire Set a timeout on key.
	//After the timeout has expired, the key will automatically be deleted.
	//Return false if the key not exist.
	//Example:
	//c.Expire("demo", 1*time.Second) // false
	//c.Set("demo", "1")
	//c.Expire("demo", 1*time.Second) // true
	Expire(k string, d time.Duration) bool
	//ExpireAt has the same effect and semantic as Expire, but instead of specifying the number of seconds representing the TTL (time to live),
	//it takes an absolute Unix Time (seconds since January 1, 1970). A Time in the past will delete the key immediately.
	//Return false if the key not exist.
	//Example:
	//c.ExpireAt("demo", time.Now().Add(10*time.Second)) // false
	//c.Set("demo", "1")
	//c.ExpireAt("demo", time.Now().Add(10*time.Second)) // true
	ExpireAt(k string, t time.Time) bool
	//Persist Remove the existing timeout on key.
	//Return false if the key not exist.
	//Example:
	//c.Persist("demo") // false
	//c.Set("demo", "1")
	//c.Persist("demo") // true
	Persist(k string) bool
	//Ttl Returns the remaining time to live of a key that has a timeout.
	//Returns 0,false if the key does not exist or if the key exist but has no associated expire.
	//Example:
	//c.Set("demo", "1")
	//c.Ttl("demo") // 0,false
	//c.Set("demo", "1", WithEx[string](10*time.Second))
	//c.Ttl("demo") // 10*time.Second,true
	Ttl(k string) (time.Duration, bool)
	// Clear all the keys
	Clear()
}

func NewMemCache

func NewMemCache[V any](opts ...ICacheOption[V]) ICache[V]

type ICacheOption

type ICacheOption[V any] func(conf *Config[V])

ICacheOption The option used to create the cache object

func WithClearInterval

func WithClearInterval[V any](d time.Duration) ICacheOption[V]

WithClearInterval set custom clear interval. Interval for clearing expired key-value pairs. The default value is 1 second If the d is 0, the periodic clearing function is disabled

func WithExpiredCallback

func WithExpiredCallback[V any](ec ExpiredCallback[V]) ICacheOption[V]

WithExpiredCallback set custom expired callback function This callback function is called when the key-value pair expires

func WithHash

func WithHash[V any](hash IHash) ICacheOption[V]

WithHash set custom hash key function

func WithShards

func WithShards[V any](shards int) ICacheOption[V]

WithShards set custom size of sharding. Default is 1024 The larger the size, the smaller the lock force, the higher the concurrency performance, and the higher the memory footprint, so try to choose a size that fits your business scenario

type IHash

type IHash interface {
	Sum64(string) uint64
}

IHash is responsible for generating unsigned, 64-bit hash of provided string. IHash should minimize collisions (generating same hash for different strings) and while performance is also important fast functions are preferable (i.e. you can use FarmHash family).

type IItem

type IItem interface {
	Expired() bool
	CanExpire() bool
	SetExpireAt(t time.Time)
}

type Item

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

func (*Item[V]) CanExpire

func (i *Item[V]) CanExpire() bool

func (*Item[V]) Expired

func (i *Item[V]) Expired() bool

func (*Item[V]) SetExpireAt

func (i *Item[V]) SetExpireAt(t time.Time)

type MemCache

type MemCache[V any] struct {
	// contains filtered or unexported fields
}

func (MemCache) Clear

func (c MemCache) Clear()

func (MemCache) Del

func (c MemCache) Del(ks ...string) int

func (MemCache) DelExpired

func (c MemCache) DelExpired(k string) bool

func (MemCache) Exists

func (c MemCache) Exists(ks ...string) bool

func (MemCache) Expire

func (c MemCache) Expire(k string, d time.Duration) bool

func (MemCache) ExpireAt

func (c MemCache) ExpireAt(k string, t time.Time) bool

func (MemCache) Get

func (c MemCache) Get(k string) (V, bool)

func (MemCache) GetDel

func (c MemCache) GetDel(k string) (V, bool)

func (MemCache) GetSet

func (c MemCache) GetSet(k string, v V, opts ...SetIOption[V]) (V, bool)

func (MemCache) Persist

func (c MemCache) Persist(k string) bool

func (MemCache) Set

func (c MemCache) Set(k string, v V, opts ...SetIOption[V]) bool

func (MemCache) Ttl

func (c MemCache) Ttl(k string) (time.Duration, bool)

type SetIOption

type SetIOption[V any] func(ICache[V], string, IItem) bool

SetIOption The option used to cache set

func WithEx

func WithEx[V any](d time.Duration) SetIOption[V]

WithEx Set the specified expire time, in time.Duration.

func WithExAt

func WithExAt[V any](t time.Time) SetIOption[V]

WithExAt Set the specified expire deadline, in time.Time.