cache

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 22, 2021 License: MIT Imports: 7 Imported by: 0

README

Cache

Golang缓存库，基于GCache做特性增强，支持设定过期缓存，LFU, LRU, ARC, Simple等缓存算法实现。

特性

  • 支持设定缓存失效时间：LFU, LRU and ARC；

  • 支持协程安全；

  • 支持监听缓存事件：evict, purge, added；(可选特性)

  • 支持全局Loader自动加载不存在的键值；(可选特性)

  • 支持外部化指定Loader加载不存在的键值；（通过GetOrLoad）

安装

$ go get github.com/bytepowered/cache

示例

手动设定Key-Value键值对
package main

import (
  "github.com/bytepowered/cache"
  "fmt"
)

func main() {
  gc := cache.New(20).
    LRU().
    Build()
  gc.Set("key", "ok")
  value, err := gc.Get("key")
  if err != nil {
    panic(err)
  }
  fmt.Println("Get:", value)
}

Get: ok
手动设定Key-Value键值对，指定缓存失效时间
package main

import (
  "github.com/bytepowered/cache"
  "fmt"
  "time"
)

func main() {
  gc := cache.New(20).
    LRU().
    Build()
  gc.SetWithExpire("key", "ok", time.Second*10)
  value, _ := gc.Get("key")
  fmt.Println("Get:", value)

  // Wait for value to expire
  time.Sleep(time.Second*10)

  value, err = gc.Get("key")
  if err != nil {
    panic(err)
  }
  fmt.Println("Get:", value)
}

Get: ok
// 10 seconds later, new attempt:
panic: ErrKeyNotFound
全局Loader加载不存在的键值
package main

import (
  "github.com/bytepowered/cache"
  "fmt"
)

func main() {
  gc := cache.New(20).
    LRU().
    LoaderFunc(func(key interface{}) (interface{}, error) {
      return "ok", nil
    }).
    Build()
  value, err := gc.Get("key")
  if err != nil {
    panic(err)
  }
  fmt.Println("Get:", value)
}

Get: ok
外部化指定Loader加载不存在的键值
package main

import (
  "github.com/bytepowered/cache"
  "fmt"
  "time"
)

func main() {
  gc := cache.New(20).
    LRU().
    Build()
  value, err := gc.GetOrLoad("key",func(key interface{}) (cache.ExpirableValue, error) {
    return cache.NewDefaultValue("my-new-value"), nil
  })
  if err != nil {
    panic(err)
  }
  fmt.Println("Get:", value)
}

Get: by-loader
全局Loader加载不存在的键值，并指定缓存失效时间
package main

import (
  "fmt"
  "time"

  "github.com/bytepowered/cache"
)

func main() {
  var evictCounter, loaderCounter, purgeCounter int
  gc := cache.New(20).
    LRU().
    LoaderExpireFunc(func(key interface{}) (cache.ExpirableValue, error) {
      loaderCounter++
      return cache.NewExpirableValue("ok", time.Second*5), nil
    }).
    EvictedFunc(func(key, value interface{}) {
      evictCounter++
      fmt.Println("evicted key:", key)
    }).
    PurgeVisitorFunc(func(key, value interface{}) {
      purgeCounter++
      fmt.Println("purged key:", key)
    }).
    Build()
  value, err := gc.Get("key")
  if err != nil {
    panic(err)
  }
  fmt.Println("Get:", value)
  time.Sleep(1 * time.Second)
  value, err = gc.Get("key")
  if err != nil {
    panic(err)
  }
  fmt.Println("Get:", value)
  gc.Purge()
  if loaderCounter != evictCounter+purgeCounter {
    panic("bad")
  }
}

Get: ok
evicted key: key
Get: ok
purged key: key

缓存算法

  • Least-Frequently Used (LFU)

Discards the least frequently used items first.

func main() {
  // size: 10
  gc := cache.New(10).
    LFU().
    Build()
  gc.Set("key", "value")
}
  • Least Recently Used (LRU)

Discards the least recently used items first.

func main() {
  // size: 10
  gc := cache.New(10).
    LRU().
    Build()
  gc.Set("key", "value")
}
  • Adaptive Replacement Cache (ARC)

Constantly balances between LRU and LFU, to improve the combined result.

detail: http://en.wikipedia.org/wiki/Adaptive_replacement_cache

func main() {
  // size: 10
  gc := cache.New(10).
    ARC().
    Build()
  gc.Set("key", "value")
}
  • SimpleCache (Default)

SimpleCache has no clear priority for evict cache. It depends on key-value map order.

func main() {
  // size: 10
  gc := cache.New(10).Build()
  gc.Set("key", "value")
  v, err := gc.Get("key")
  if err != nil {
    panic(err)
  }
}

Loading Cache

If specified LoaderFunc, values are automatically loaded by the cache, and are stored in the cache until either evicted or manually invalidated.

func main() {
  gc := cache.New(10).
    LRU().
    LoaderFunc(func(key interface{}) (interface{}, error) {
      return "value", nil
    }).
    Build()
  v, _ := gc.Get("key")
  // output: "value"
  fmt.Println(v)
}

GCache coordinates cache fills such that only one load in one process of an entire replicated set of processes populates the cache, then multiplexes the loaded value to all callers.

Expirable cache

func main() {
  // LRU cache, size: 10, expiration: after a hour
  gc := cache.New(10).
    LRU().
    Expiration(time.Hour).
    Build()
}

事件处理

Evicted handler

Event handler for evict the entry.

func main() {
  gc := cache.New(2).
    EvictedFunc(func(key, value interface{}) {
      fmt.Println("evicted key:", key)
    }).
    Build()
  for i := 0; i < 3; i++ {
    gc.Set(i, i*i)
  }
}

evicted key: 0
Added handler

Event handler for add the entry.

func main() {
  gc := cache.New(2).
    AddedFunc(func(key, value interface{}) {
      fmt.Println("added key:", key)
    }).
    Build()
  for i := 0; i < 3; i++ {
    gc.Set(i, i*i)
  }
}

added key: 0
added key: 1
added key: 2

Authors

Yongjia Chen @2020

Jun Kimura @2019

Documentation

Index

Constants

View Source 
const (
	TypeSimple = "simple"
	TypeLru    = "lru"
	TypeLfu    = "lfu"
	TypeArc    = "arc"
)

Variables

View Source 
var KeyNotFoundError = errors.New("key not found")
View Source 
var NoExpiration *time.Duration = nil

Functions

This section is empty.

Types

type ARC 

type ARC struct {
	BaseCache
	// contains filtered or unexported fields
}

Constantly balances between LRU and LFU, to improve the combined result.

func (*ARC) Get 

func (c *ARC) Get(key interface{}) (interface{}, error)

Get a value from cache pool using key if it exists. If not exists and it has LoaderFunc, it will generate the value using you have specified LoaderFunc method returns value.

func (*ARC) GetAll 

func (c *ARC) GetAll(checkExpired bool) map[interface{}]interface{}

GetAll returns all key-value pairs in the cache.

func (*ARC) GetIfPresent 

func (c *ARC) GetIfPresent(key interface{}) (interface{}, error)

GetIfPresent gets a value from cache pool using key if it exists. If it dose not exists key, returns KeyNotFoundError. And send a request which refresh value for specified key if cache object has LoaderFunc.

func (*ARC) GetOrLoad 

func (c *ARC) GetOrLoad(key interface{}, loader LoaderExpireFunc) (interface{}, error)

Get a value from cache pool using key if it exists. If not exists, it will generate the value using given specified LoaderFunc method returns value.

func (*ARC) Has 

func (c *ARC) Has(key interface{}) bool

Has checks if key exists in cache

func (ARC) HitCount added in v0.2.0 

func (st ARC) HitCount() uint64

HitCount returns hit count

func (ARC) HitRate added in v0.2.0 

func (st ARC) HitRate() float64

HitRate returns rate for cache hitting

func (ARC) IncrHitCount added in v0.2.0 

func (st ARC) IncrHitCount() uint64

increment hit count

func (ARC) IncrMissCount added in v0.2.0 

func (st ARC) IncrMissCount() uint64

increment miss count

func (*ARC) Keys 

func (c *ARC) Keys(checkExpired bool) []interface{}

Keys returns a slice of the keys in the cache.

func (*ARC) Len 

func (c *ARC) Len(checkExpired bool) int

Len returns the number of items in the cache.

func (ARC) LookupCount added in v0.2.0 

func (st ARC) LookupCount() uint64

LookupCount returns lookup count

func (ARC) MissCount added in v0.2.0 

func (st ARC) MissCount() uint64

MissCount returns miss count

func (*ARC) Purge 

func (c *ARC) Purge()

Purge is used to completely clear the cache

func (*ARC) Remove 

func (c *ARC) Remove(key interface{}) bool

Remove removes the provided key from the cache.

func (*ARC) Set 

func (c *ARC) Set(key, value interface{}) error

func (*ARC) SetWithExpire 

func (c *ARC) SetWithExpire(key, value interface{}, expiration time.Duration) error

Set a new key-value pair with an expiration time

type AddedFunc 

type AddedFunc func(interface{}, interface{})

type BaseCache added in v0.2.0 

type BaseCache struct {
	// contains filtered or unexported fields
}

func (BaseCache) HitCount added in v0.2.0 

func (st BaseCache) HitCount() uint64

HitCount returns hit count

func (BaseCache) HitRate added in v0.2.0 

func (st BaseCache) HitRate() float64

HitRate returns rate for cache hitting

func (BaseCache) IncrHitCount added in v0.2.0 

func (st BaseCache) IncrHitCount() uint64

increment hit count

func (BaseCache) IncrMissCount added in v0.2.0 

func (st BaseCache) IncrMissCount() uint64

increment miss count

func (BaseCache) LookupCount added in v0.2.0 

func (st BaseCache) LookupCount() uint64

LookupCount returns lookup count

func (BaseCache) MissCount added in v0.2.0 

func (st BaseCache) MissCount() uint64

MissCount returns miss count

type Builder added in v0.2.0 

type Builder struct {
	// contains filtered or unexported fields
}

func New 

func New(size int) *Builder

func NewARC added in v0.2.0 

func NewARC(size int) *Builder

func NewLFU added in v0.2.0 

func NewLFU(size int) *Builder

func NewLRU added in v0.2.0 

func NewLRU(size int) *Builder

func NewWithEvictType added in v0.2.0 

func NewWithEvictType(size int, tp string) *Builder

func (*Builder) ARC added in v0.2.0 

func (b *Builder) ARC() *Builder

func (*Builder) AddedFunc added in v0.2.0 

func (b *Builder) AddedFunc(addedFunc AddedFunc) *Builder

func (*Builder) Build added in v0.2.0 

func (b *Builder) Build() Cache

func (*Builder) Clock added in v0.2.0 

func (b *Builder) Clock(clock Clock) *Builder

func (*Builder) DeserializeFunc added in v0.2.0 

func (b *Builder) DeserializeFunc(deserializeFunc DeserializeFunc) *Builder

func (*Builder) EvictType added in v0.2.0 

func (b *Builder) EvictType(tp string) *Builder

func (*Builder) EvictedFunc added in v0.2.0 

func (b *Builder) EvictedFunc(evictedFunc EvictedFunc) *Builder

func (*Builder) Expiration added in v0.2.0 

func (b *Builder) Expiration(expiration time.Duration) *Builder

func (*Builder) LFU added in v0.2.0 

func (b *Builder) LFU() *Builder

func (*Builder) LRU added in v0.2.0 

func (b *Builder) LRU() *Builder

func (*Builder) LoaderExpireFunc added in v0.2.0 

func (b *Builder) LoaderExpireFunc(loaderExpireFunc LoaderExpireFunc) *Builder

Set a loader function with expiration. loaderExpireFunc: create a new value with this function if cached value is expired. If nil returned instead of time.Duration from loaderExpireFunc than value will never expire.

func (*Builder) LoaderFunc added in v0.2.0 

func (b *Builder) LoaderFunc(loaderFunc LoaderFunc) *Builder

Set a loader function. loaderFunc: create a new value with this function if cached value is expired.

func (*Builder) PurgeVisitorFunc added in v0.2.0 

func (b *Builder) PurgeVisitorFunc(purgeVisitorFunc PurgeVisitorFunc) *Builder

func (*Builder) SerializeFunc added in v0.2.0 

func (b *Builder) SerializeFunc(serializeFunc SerializeFunc) *Builder

func (*Builder) Simple added in v0.2.0 

func (b *Builder) Simple() *Builder

type Cache 

type Cache interface {
	Set(key, value interface{}) error
	SetWithExpire(key, value interface{}, expiration time.Duration) error
	Get(key interface{}) (interface{}, error)
	GetOrLoad(key interface{}, loader LoaderExpireFunc) (interface{}, error)
	GetIfPresent(key interface{}) (interface{}, error)
	GetAll(checkExpired bool) map[interface{}]interface{}
	Remove(key interface{}) bool
	Purge()
	Keys(checkExpired bool) []interface{}
	Len(checkExpired bool) int
	Has(key interface{}) bool
	// contains filtered or unexported methods
}

type Clock 

type Clock interface {
	Now() time.Time
}

func NewRealClock 

func NewRealClock() Clock

type DeserializeFunc 

type DeserializeFunc func(interface{}, interface{}) (interface{}, error)

type EvictedFunc 

type EvictedFunc func(interface{}, interface{})

type Expirable added in v0.3.0 

type Expirable struct {
	Value  interface{}   // Value
	Expire time.Duration // Specified expiration of this value; expire<=0 will use default
}

func NewDefault added in v0.3.0 

func NewDefault(value interface{}) Expirable

func NewExpirable added in v0.3.0 

func NewExpirable(value interface{}, expire time.Duration) Expirable

type FakeClock 

type FakeClock interface {
	Clock

	Advance(d time.Duration)
}

func NewFakeClock 

func NewFakeClock() FakeClock

type Group 

type Group struct {
	// contains filtered or unexported fields
}

Group represents a class of work and forms a namespace in which units of work can be executed with duplicate suppression.

func (*Group) Do 

func (g *Group) Do(key interface{}, fn func() (interface{}, error), isWait bool) (interface{}, bool, error)

Do executes and returns the results of the given function, making sure that only one execution is in-flight for a given key at a time. If a duplicate comes in, the duplicate caller waits for the original to complete and receives the same results.

type LFUCache 

type LFUCache struct {
	BaseCache
	// contains filtered or unexported fields
}

Discards the least frequently used items first.

func (*LFUCache) Get 

func (c *LFUCache) Get(key interface{}) (interface{}, error)

Get a value from cache pool using key if it exists. If it dose not exists key and has LoaderFunc, generate a value using `LoaderFunc` method returns value.

func (*LFUCache) GetAll 

func (c *LFUCache) GetAll(checkExpired bool) map[interface{}]interface{}

GetAll returns all key-value pairs in the cache.

func (*LFUCache) GetIfPresent 

func (c *LFUCache) GetIfPresent(key interface{}) (interface{}, error)

GetIfPresent gets a value from cache pool using key if it exists. If it dose not exists key, returns KeyNotFoundError. And send a request which refresh value for specified key if cache object has LoaderFunc.

func (*LFUCache) GetOrLoad 

func (c *LFUCache) GetOrLoad(key interface{}, loader LoaderExpireFunc) (interface{}, error)

Get a value from cache pool using key if it exists. If it dose not exists key, generate a value using `LoaderFunc` method returns value.

func (*LFUCache) Has 

func (c *LFUCache) Has(key interface{}) bool

Has checks if key exists in cache

func (LFUCache) HitCount added in v0.2.0 

func (st LFUCache) HitCount() uint64

HitCount returns hit count

func (LFUCache) HitRate added in v0.2.0 

func (st LFUCache) HitRate() float64

HitRate returns rate for cache hitting

func (LFUCache) IncrHitCount added in v0.2.0 

func (st LFUCache) IncrHitCount() uint64

increment hit count

func (LFUCache) IncrMissCount added in v0.2.0 

func (st LFUCache) IncrMissCount() uint64

increment miss count

func (*LFUCache) Keys 

func (c *LFUCache) Keys(checkExpired bool) []interface{}

Keys returns a slice of the keys in the cache.

func (*LFUCache) Len 

func (c *LFUCache) Len(checkExpired bool) int

Len returns the number of items in the cache.

func (LFUCache) LookupCount added in v0.2.0 

func (st LFUCache) LookupCount() uint64

LookupCount returns lookup count

func (LFUCache) MissCount added in v0.2.0 

func (st LFUCache) MissCount() uint64

MissCount returns miss count

func (*LFUCache) Purge 

func (c *LFUCache) Purge()

Completely clear the cache

func (*LFUCache) Remove 

func (c *LFUCache) Remove(key interface{}) bool

Remove removes the provided key from the cache.

func (*LFUCache) Set 

func (c *LFUCache) Set(key, value interface{}) error

Set a new key-value pair

func (*LFUCache) SetWithExpire 

func (c *LFUCache) SetWithExpire(key, value interface{}, expiration time.Duration) error

Set a new key-value pair with an expiration time

type LRUCache 

type LRUCache struct {
	BaseCache
	// contains filtered or unexported fields
}

Discards the least recently used items first.

func (*LRUCache) Get 

func (c *LRUCache) Get(key interface{}) (interface{}, error)

Get a value from cache pool using key if it exists. If it dose not exists key and has LoaderFunc, generate a value using `LoaderFunc` method returns value.

func (*LRUCache) GetAll 

func (c *LRUCache) GetAll(checkExpired bool) map[interface{}]interface{}

GetAll returns all key-value pairs in the cache.

func (*LRUCache) GetIfPresent 

func (c *LRUCache) GetIfPresent(key interface{}) (interface{}, error)

GetIfPresent gets a value from cache pool using key if it exists. If it dose not exists key, returns KeyNotFoundError. And send a request which refresh value for specified key if cache object has LoaderFunc.

func (*LRUCache) GetOrLoad 

func (c *LRUCache) GetOrLoad(key interface{}, loader LoaderExpireFunc) (interface{}, error)

Get a value from cache pool using key if it exists. If it dose not exists key, generate a value using `LoaderFunc` method returns value.

func (*LRUCache) Has 

func (c *LRUCache) Has(key interface{}) bool

Has checks if key exists in cache

func (LRUCache) HitCount added in v0.2.0 

func (st LRUCache) HitCount() uint64

HitCount returns hit count

func (LRUCache) HitRate added in v0.2.0 

func (st LRUCache) HitRate() float64

HitRate returns rate for cache hitting

func (LRUCache) IncrHitCount added in v0.2.0 

func (st LRUCache) IncrHitCount() uint64

increment hit count

func (LRUCache) IncrMissCount added in v0.2.0 

func (st LRUCache) IncrMissCount() uint64

increment miss count

func (*LRUCache) Keys 

func (c *LRUCache) Keys(checkExpired bool) []interface{}

Keys returns a slice of the keys in the cache.

func (*LRUCache) Len 

func (c *LRUCache) Len(checkExpired bool) int

Len returns the number of items in the cache.

func (LRUCache) LookupCount added in v0.2.0 

func (st LRUCache) LookupCount() uint64

LookupCount returns lookup count

func (LRUCache) MissCount added in v0.2.0 

func (st LRUCache) MissCount() uint64

MissCount returns miss count

func (*LRUCache) Purge 

func (c *LRUCache) Purge()

Completely clear the cache

func (*LRUCache) Remove 

func (c *LRUCache) Remove(key interface{}) bool

Remove removes the provided key from the cache.

func (*LRUCache) Set 

func (c *LRUCache) Set(key, value interface{}) error

set a new key-value pair

func (*LRUCache) SetWithExpire 

func (c *LRUCache) SetWithExpire(key, value interface{}, expiration time.Duration) error

Set a new key-value pair with an expiration time

type LoaderExpireFunc 

type LoaderExpireFunc func(interface{}) (Expirable, error)

type LoaderFunc 

type LoaderFunc func(interface{}) (interface{}, error)

type PurgeVisitorFunc 

type PurgeVisitorFunc func(interface{}, interface{})

type RealClock 

type RealClock struct{}

func (RealClock) Now 

func (rc RealClock) Now() time.Time

type SerializeFunc 

type SerializeFunc func(interface{}, interface{}) (interface{}, error)

type SimpleCache 

type SimpleCache struct {
	BaseCache
	// contains filtered or unexported fields
}

SimpleCache has no clear priority for evict cache. It depends on key-value map order.

func (*SimpleCache) Get 

func (c *SimpleCache) Get(key interface{}) (interface{}, error)

Get a value from cache pool using key if it exists. If it dose not exists key and has LoaderFunc, generate a value using `LoaderFunc` method returns value.

func (*SimpleCache) GetAll 

func (c *SimpleCache) GetAll(checkExpired bool) map[interface{}]interface{}

GetAll returns all key-value pairs in the cache.

func (*SimpleCache) GetIfPresent 

func (c *SimpleCache) GetIfPresent(key interface{}) (interface{}, error)

GetIfPresent gets a value from cache pool using key if it exists. If it dose not exists key, returns KeyNotFoundError. And send a request which refresh value for specified key if cache object has LoaderFunc.

func (*SimpleCache) GetOrLoad 

func (c *SimpleCache) GetOrLoad(key interface{}, loader LoaderExpireFunc) (interface{}, error)

Get a value from cache pool using key if it exists. If it dose not exists key, generate a value using `LoaderFunc` method returns value.

func (*SimpleCache) Has 

func (c *SimpleCache) Has(key interface{}) bool

Has checks if key exists in cache

func (SimpleCache) HitCount added in v0.2.0 

func (st SimpleCache) HitCount() uint64

HitCount returns hit count

func (SimpleCache) HitRate added in v0.2.0 

func (st SimpleCache) HitRate() float64

HitRate returns rate for cache hitting

func (SimpleCache) IncrHitCount added in v0.2.0 

func (st SimpleCache) IncrHitCount() uint64

increment hit count

func (SimpleCache) IncrMissCount added in v0.2.0 

func (st SimpleCache) IncrMissCount() uint64

increment miss count

func (*SimpleCache) Keys 

func (c *SimpleCache) Keys(checkExpired bool) []interface{}

Keys returns a slice of the keys in the cache.

func (*SimpleCache) Len 

func (c *SimpleCache) Len(checkExpired bool) int

Len returns the number of items in the cache.

func (SimpleCache) LookupCount added in v0.2.0 

func (st SimpleCache) LookupCount() uint64

LookupCount returns lookup count

func (SimpleCache) MissCount added in v0.2.0 

func (st SimpleCache) MissCount() uint64

MissCount returns miss count

func (*SimpleCache) Purge 

func (c *SimpleCache) Purge()

Completely clear the cache

func (*SimpleCache) Remove 

func (c *SimpleCache) Remove(key interface{}) bool

Remove removes the provided key from the cache.

func (*SimpleCache) Set 

func (c *SimpleCache) Set(key, value interface{}) error

Set a new key-value pair

func (*SimpleCache) SetWithExpire 

func (c *SimpleCache) SetWithExpire(key, value interface{}, expiration time.Duration) error

Set a new key-value pair with an expiration time

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.