README
¶
🍰 cachego
cachego 是一个拥有分片机制的轻量级内存缓存库，API 友好，支持多种数据淘汰机制，可以应用于所有的 GoLang 应用程序中。
目前已经在多个线上服务中运行稳定，服务日常请求过万 qps，最高抵御过 96w/s qps 的冲击，欢迎使用！👏🏻
🕹 功能特性
- 以键值对形式缓存数据，极简的 API 设计风格
- 引入 option function 模式，简化创建缓存参数
- 提供 ttl 过期机制，支持限制键值对数量
- 提供 lru 清理机制，提供 lfu 清理机制
- 提供锁粒度更细的分片缓存，具有非常高的并发性能
- 支持懒清理机制，每一次访问的时候判断是否过期
- 支持哨兵清理机制，每隔一定的时间间隔进行清理
- 自带 singleflight 机制，减少缓存穿透的伤害
- 自带定时任务封装，方便热数据定时加载到缓存
- 支持上报缓存状况，可自定义多个缓存上报点
- 自带快速时钟，支持纳秒级获取时间
历史版本的特性请查看 HISTORY.md。未来版本的新特性和计划请查看 FUTURE.md。
🚀 安装方式
$ go get -u github.com/FishGoddess/cachego
💡 参考案例
package main
import (
"fmt"
"time"
"github.com/FishGoddess/cachego"
)
func main() {
// Use NewCache function to create a cache.
// By default, it creates a standard cache which evicts entries randomly.
// Use WithShardings to shard cache to several parts for higher performance.
// Use WithGC to clean expired entries every 10 minutes.
cache := cachego.NewCache(cachego.WithGC(10*time.Minute), cachego.WithShardings(64))
// Set an entry to cache with ttl.
cache.Set("key", 123, time.Second)
// Get an entry from cache.
value, ok := cache.Get("key")
fmt.Println(value, ok) // 123 true
// Check how many entries stores in cache.
size := cache.Size()
fmt.Println(size) // 1
// Clean expired entries.
cleans := cache.GC()
fmt.Println(cleans) // 1
// Set an entry which doesn't have ttl.
cache.Set("key", 123, cachego.NoTTL)
// Remove an entry.
removedValue := cache.Remove("key")
fmt.Println(removedValue) // 123
// Reset resets cache to initial status.
cache.Reset()
// Get value from cache and load it to cache if not found.
value, ok = cache.Get("key")
if !ok {
// Loaded entry will be set to cache and returned.
// By default, it will use singleflight.
value, _ = cache.Load("key", time.Second, func() (value interface{}, err error) {
return 666, nil
})
}
fmt.Println(value) // 666
// You can use WithLRU to specify the type of cache to lru.
// Also, try WithLFU if you want to use lfu to evict data.
cache = cachego.NewCache(cachego.WithLRU(100))
cache = cachego.NewCache(cachego.WithLFU(100))
// Use NewCacheWithReport to create a cache with report.
cache, reporter := cachego.NewCacheWithReport(cachego.WithCacheName("test"))
fmt.Println(reporter.CacheName())
fmt.Println(reporter.CacheType())
}
更多使用案例请查看 _examples 目录。
🔥 性能测试
$ make bench
goos: darwin
goarch: amd64
cpu: Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz
BenchmarkCachegoGet-12 25214618 47.2 ns/op 0 B/op 0 allocs/op
BenchmarkCachegoGetLRU-12 8169417 149.0 ns/op 0 B/op 0 allocs/op
BenchmarkCachegoGetLFU-12 7071300 171.6 ns/op 0 B/op 0 allocs/op
BenchmarkCachegoGetSharding-12 72568048 16.8 ns/op 0 B/op 0 allocs/op
BenchmarkGcacheGet-12 4765129 252.1 ns/op 16 B/op 1 allocs/op
BenchmarkGcacheGetLRU-12 5735739 214.0 ns/op 16 B/op 1 allocs/op
BenchmarkGcacheGetLFU-12 4830048 250.8 ns/op 16 B/op 1 allocs/op
BenchmarkEcacheGet-12 11515140 101.0 ns/op 0 B/op 0 allocs/op
BenchmarkEcache2Get-12 12255506 95.6 ns/op 0 B/op 0 allocs/op
BenchmarkBigcacheGet-12 21711988 60.4 ns/op 7 B/op 2 allocs/op
BenchmarkFreecacheGet-12 24903388 44.3 ns/op 27 B/op 2 allocs/op
BenchmarkGoCacheGet-12 19818014 61.4 ns/op 0 B/op 0 allocs/op
BenchmarkCachegoSet-12 5743768 209.6 ns/op 16 B/op 1 allocs/op
BenchmarkCachegoSetLRU-12 6105316 189.9 ns/op 16 B/op 1 allocs/op
BenchmarkCachegoSetLFU-12 5505601 217.2 ns/op 16 B/op 1 allocs/op
BenchmarkCachegoSetSharding-12 39012607 31.2 ns/op 16 B/op 1 allocs/op
BenchmarkGcacheSet-12 3326841 365.3 ns/op 56 B/op 3 allocs/op
BenchmarkGcacheSetLRU-12 3471307 318.7 ns/op 56 B/op 3 allocs/op
BenchmarkGcacheSetLFU-12 3896512 335.1 ns/op 56 B/op 3 allocs/op
BenchmarkEcacheSet-12 7318136 167.5 ns/op 32 B/op 2 allocs/op
BenchmarkEcache2Set-12 7020867 175.7 ns/op 32 B/op 2 allocs/op
BenchmarkBigcacheSet-12 4107825 268.9 ns/op 55 B/op 0 allocs/op
BenchmarkFreecacheSet-12 44181687 28.4 ns/op 0 B/op 0 allocs/op
BenchmarkGoCacheSet-12 4921483 249.0 ns/op 16 B/op 1 allocs/op
注：Ecache 只有 LRU 模式，v1 和 v2 两个版本；Freecache 默认是 256 分片，无法调节为 1 个分片进行对比测试。
👥 贡献者
- cristiane：提供 hash 算法的优化建议
- hzy15610046011：提供架构设计文档和图片
- chen661：提供 segmentSize 设置选项的参数限制想法
如果您觉得 cachego 缺少您需要的功能，请不要犹豫，马上参与进来，发起一个 issue。
Documentation
¶
Index ¶
- Constants
- func NewCacheWithReport(opts ...Option) (cache Cache, reporter *Reporter)
- func RunGCTask(cache Cache, duration time.Duration) (cancel func())
- func SetMapInitialCap(initialCap int)
- func SetSliceInitialCap(initialCap int)
- type Cache
- type CacheType
- type Option
- func WithCacheName(cacheName string) Option
- func WithDisableSingleflight() Option
- func WithGC(gcDuration time.Duration) Option
- func WithHash(hash func(key string) int) Option
- func WithLFU(maxEntries int) Option
- func WithLRU(maxEntries int) Option
- func WithMaxEntries(maxEntries int) Option
- func WithMaxScans(maxScans int) Option
- func WithNow(now func() int64) Option
- func WithRecordGC(recordGC bool) Option
- func WithRecordHit(recordHit bool) Option
- func WithRecordLoad(recordLoad bool) Option
- func WithRecordMissed(recordMissed bool) Option
- func WithReportGC(reportGC func(reporter *Reporter, cost time.Duration, cleans int)) Option
- func WithReportHit(reportHit func(reporter *Reporter, key string, value interface{})) Option
- func WithReportLoad(...) Option
- func WithReportMissed(reportMissed func(reporter *Reporter, key string)) Option
- func WithShardings(shardings int) Option
- type Reporter
- func (r *Reporter) CacheGC() time.Duration
- func (r *Reporter) CacheName() string
- func (r *Reporter) CacheShardings() int
- func (r *Reporter) CacheSize() int
- func (r *Reporter) CacheType() CacheType
- func (r *Reporter) CountGC() uint64
- func (r *Reporter) CountHit() uint64
- func (r *Reporter) CountLoad() uint64
- func (r *Reporter) CountMissed() uint64
- func (r *Reporter) HitRate() float64
- func (r *Reporter) MissedRate() float64
Constants ¶
const (
// NoTTL means a key is never expired.
NoTTL = 0
)
Variables ¶
This section is empty.
Functions ¶
func NewCacheWithReport ¶ added in v0.4.6
NewCacheWithReport creates a cache and a reporter with options. By default, it will create a standard cache which uses one lock to solve data race. It may cause a big performance problem in high concurrency. You can use WithShardings to create a sharding cache which is good for concurrency. Also, you can use options to specify the type of cache to others, such as lru.
func RunGCTask ¶ added in v0.4.6
RunGCTask runs a gc task in a new goroutine and returns a cancel function to cancel the task. However, you don't need to call it manually for most time, instead, use options is a better choice. Making it a public function is for more customizations in some situations. For example, using options to run gc task is un-cancelable, so you can use it to run gc task by your own and get a cancel function to cancel the gc task.
func SetMapInitialCap ¶ added in v0.4.6
func SetMapInitialCap(initialCap int)
SetMapInitialCap sets the initial capacity of map.
func SetSliceInitialCap ¶ added in v0.4.6
func SetSliceInitialCap(initialCap int)
SetSliceInitialCap sets the initial capacity of slice.
Types ¶
type Cache ¶
type Cache interface {
// Get gets the value of key from cache and returns value if found.
// A nil value will be returned if key doesn't exist in cache.
// Notice that we won't remove expired keys in get method, so you should remove them manually or set a limit of keys.
// The reason why we won't remove expired keys in get method is for higher re-usability, because we often set a new value
// of expired key after getting it (so we can reuse the memory of entry).
Get(key string) (value interface{}, found bool)
// Set sets key and value to cache with ttl and returns evicted value if exists.
// See NoTTL if you want your key is never expired.
Set(key string, value interface{}, ttl time.Duration) (evictedValue interface{})
// Remove removes key and returns the removed value of key.
// A nil value will be returned if key doesn't exist in cache.
Remove(key string) (removedValue interface{})
// Size returns the count of keys in cache.
// The result may be different in different implements.
Size() (size int)
// GC cleans the expired keys in cache and returns the exact count cleaned.
// The exact cleans depend on implements, however, all implements should have a limit of scanning.
GC() (cleans int)
// Reset resets cache to initial status which is like a new cache.
Reset()
// Load loads a key with ttl to cache and returns an error if failed.
// We recommend you use this method to load missed keys to cache,
// because it may use singleflight to reduce the times calling load function.
Load(key string, ttl time.Duration, load func() (value interface{}, err error)) (value interface{}, err error)
}
Cache is the core interface of cachego. We provide some implements including standard cache and sharding cache.
func NewCache ¶
NewCache creates a cache with options. By default, it will create a standard cache which uses one lock to solve data race. It may cause a big performance problem in high concurrency. You can use WithShardings to create a sharding cache which is good for concurrency. Also, you can use options to specify the type of cache to others, such as lru. Use NewCacheWithReporter to get a reporter for use if you want.
type CacheType ¶ added in v0.4.10
type CacheType string
CacheType is the type of cache.
func (CacheType) IsStandard ¶ added in v0.4.10
IsStandard returns if cache type is standard.
type Option ¶ added in v0.2.1
type Option func(conf *config)
Option applies to config and sets some values to config.
func WithCacheName ¶ added in v0.4.8
WithCacheName returns an option setting the cacheName of config.
func WithDisableSingleflight ¶ added in v0.3.2
func WithDisableSingleflight() Option
WithDisableSingleflight returns an option turning off singleflight mode of cache.
func WithGC ¶ added in v0.4.6
WithGC returns an option setting the duration of cache gc. Negative value means no gc.
func WithHash ¶ added in v0.4.6
WithHash returns an option setting the hash function of cache. A hash function should return the hash code of key.
func WithLFU ¶ added in v0.4.6
WithLFU returns an option setting the type of cache to lfu. Notice that lfu cache must have max entries limit, so you have to specify a maxEntries.
func WithLRU ¶ added in v0.4.6
WithLRU returns an option setting the type of cache to lru. Notice that lru cache must have max entries limit, so you have to specify a maxEntries.
func WithMaxEntries ¶ added in v0.4.6
WithMaxEntries returns an option setting the max entries of cache. Negative value means no limit.
func WithMaxScans ¶ added in v0.4.6
WithMaxScans returns an option setting the max scans of cache. Negative value means no limit.
func WithNow ¶ added in v0.4.6
WithNow returns an option setting the now function of cache. A now function should return a nanosecond unix time.
func WithRecordGC ¶ added in v0.4.6
WithRecordGC returns an option setting the recordGC of config.
func WithRecordHit ¶ added in v0.4.6
WithRecordHit returns an option setting the recordHit of config.
func WithRecordLoad ¶ added in v0.4.6
WithRecordLoad returns an option setting the recordLoad of config.
func WithRecordMissed ¶ added in v0.4.6
WithRecordMissed returns an option setting the recordMissed of config.
func WithReportGC ¶ added in v0.4.6
WithReportGC returns an option setting the reportGC of config.
func WithReportHit ¶ added in v0.4.6
WithReportHit returns an option setting the reportHit of config.
func WithReportLoad ¶ added in v0.4.6
func WithReportLoad(reportLoad func(reporter *Reporter, key string, value interface{}, ttl time.Duration, err error)) Option
WithReportLoad returns an option setting the reportLoad of config.
func WithReportMissed ¶ added in v0.4.6
WithReportMissed returns an option setting the reportMissed of config.
func WithShardings ¶ added in v0.4.6
WithShardings returns an option setting the sharding count of cache. Negative value means no sharding.
type Reporter ¶ added in v0.4.6
type Reporter struct {
// contains filtered or unexported fields
}
Reporter stores some values for reporting.
func (*Reporter) CacheGC ¶ added in v0.4.12
CacheGC returns the gc duration of cache. You can use WithGC to set cache's gc duration. Zero duration means cache disables gc.
func (*Reporter) CacheName ¶ added in v0.4.8
CacheName returns the name of cache. You can use WithCacheName to set cache's name.
func (*Reporter) CacheShardings ¶ added in v0.4.9
CacheShardings returns the shardings of cache. You can use WithShardings to set cache's shardings. Zero shardings means cache is non-sharding.
func (*Reporter) CountMissed ¶ added in v0.4.6
CountMissed returns the missed count.
func (*Reporter) MissedRate ¶ added in v0.4.6
MissedRate returns the missed rate.
Source Files
Directories