README
¶
📜 cachego
cachego 是一个拥有高性能分段锁机制的轻量级内存缓存，拥有懒清理和哨兵清理两种清理机制，可以应用于所有的 GoLang 应用程序中。
🕹 功能特性
- 以键值对形式缓存数据，极简的 API 设计风格
- 引入 option function 模式，可定制化创建缓存的过程
- 加入 debug 调试点，可以在开发的时候验证缓存的命中情况
- 使用粒度更细的分段锁机制进行设计，具有非常高的并发性能
- 支持懒清理机制，每一次访问的时候判断是否过期
- 支持哨兵清理机制，每隔一定的时间间隔进行清理
历史版本的特性请查看 HISTORY.md。未来版本的新特性和计划请查看 FUTURE.md。
具体设计可以参考 架构设计介绍 文档。
🚀 安装方式
$ go get -u github.com/FishGoddess/cachego
💡 参考案例
package main
import (
"fmt"
"time"
"github.com/FishGoddess/cachego"
)
func main() {
// Create a cache for use.
// We use option function to customize the creation of cache.
// WithAutoGC means it will do gc automatically.
cache := cachego.NewCache(cachego.WithAutoGC(10 * time.Minute))
// Set a new entry to cache.
cache.Set("key", 666)
// Get returns the value of this key.
v, ok := cache.Get("key")
fmt.Println(v, ok) // Output: 666 true
// If you pass a not existed key to of method, nil and false will be returned.
v, ok = cache.Get("not existed key")
fmt.Println(v, ok) // Output: <nil> false
// SetWithTTL sets an entry with expired time.
// The unit of expired time is second.
// See more information in example of ttl.
cache.SetWithTTL("ttlKey", 123, 10)
// Also, you can get value from cache first, then load it to cache if missed.
// onMissed is usually used to get data from db or somewhere, so you can refresh the value in cache.
cache.GetWithLoad("newKey", func() (data interface{}, ttl int64, err error) {
return "newValue", 3, nil
})
}
更多使用案例请查看 _examples 目录。
🔥 性能测试
$ go test -v ./_examples/performance_test.go
总缓存数据为 100w 条，并发数为 10w，循环测试写入和读取次数为 50 次
测试环境：R7-5800X CPU @ 3.8GHZ GHZ，32 GB RAM
| 测试 | 写入消耗时间 (越小越好) | 读取消耗时间 (越小越好) | 混合操作消耗时间 (越小越好) |
|---|---|---|---|
| cachego | 965ms | 949ms | 991ms |
| go-cache | 3216ms | 980ms | 4508ms |
| freeCache | 954ms | 968ms | 987ms |
可以看出，由于使用了分段锁机制，读写性能在并发下依然非常高，但是分段锁会多一次定位的操作，如果加锁的消耗小于定位的消耗，那分段锁就不占优势。 这也是为什么 cachego 在写入性能上比 go-cache 强一大截，但是读取性能却没强多少的原因。后续会着重优化读取性能！
👥 贡献者
- cristiane：提供 hash 算法的优化建议
- hzy15610046011：提供架构设计文档和图片
如果您觉得 cachego 缺少您需要的功能，请不要犹豫，马上参与进来，发起一个 issue。
Documentation
¶
Overview ¶
Package cache provides an easy way to use foundation for your caching operations.
1. the basic usage:
// Create a cache for use.
// We use option function to customize the creation of cache.
// WithAutoGC means it will do gc automatically.
cache := cachego.NewCache(cachego.WithAutoGC(10 * time.Minute))
// Set a new entry to cache.
cache.Set("key", 666)
// Get returns the value of this key.
v, ok := cache.Get("key")
fmt.Println(v, ok) // Output: 666 true
// If you pass a not existed key to of method, nil and false will be returned.
v, ok = cache.Get("not existed key")
fmt.Println(v, ok) // Output: <nil> false
// SetWithTTL sets an entry with expired time.
// The unit of expired time is second.
// See more information in example of ttl.
cache.SetWithTTL("ttlKey", 123, 10)
// Also, you can get value from cache first, then load it to cache if missed.
// onMissed is usually used to get data from db or somewhere, so you can refresh the value in cache.
cache.GetWithLoad("newKey", func() (data interface{}, ttl int64, err error) {
return "newValue", 3, nil
})
2. the ttl usage:
// Create a cache and set an entry to cache.
// The ttl is 3 seconds.
cache := cachego.NewCache()
cache.SetWithTTL("key", "value", 3)
// Check if the key is alive.
value, ok := cache.Get("key")
fmt.Println(value, ok) // Output: value true
// Wait for 5 seconds and check again.
// Now the key is gone.
time.Sleep(5 * time.Second)
value, ok = cache.Get("key")
fmt.Println(value, ok) // Output: <nil> false
// However, the key is still in cache and you should remove it by Remove() or RemoveAll().
// So, we provide an automatic way to remove those who are dead. See more information in example of gc.
cache.AutoGc(10 * time.Minute)
3. the gc usage:
// Create a cache and set an entry to cache.
// The ttl is 1 second.
cache := cachego.NewCache()
cache.SetWithTTL("key", "value", 1)
// Wait for 2 seconds and check the key.
time.Sleep(2 * time.Second)
// We can see this key is gone and we can't get it anymore.
value, ok := cache.Get("key")
fmt.Println(value, ok) // Output: <nil> false
// However, the key still stores in cache and occupies the space.
size := cache.Size()
fmt.Println(size) // Output: 1
// We should call Gc() to clean up these dead entries.
// Notice that this method will takes some CPU time to finish this task.
cache.Gc()
size = cache.Size()
fmt.Println(size) // Output: 0
// Also, we provide an automatic way to do this job at fixed duration.
// It returns a channel which can be used to stop this automatic job.
// If you want to stop it, just send an true or false to the chan!
stopAutoGc := cache.AutoGc(10 * time.Minute)
stopAutoGc <- struct{}{}
4. the option usage:
// We use option function to customize the creation of cache.
// You can just new it without options.
cache := cachego.NewCache()
cache.Set("key", "value")
// You can set it to a cache with automatic gc if you want
// Try WithAutoGC.
cache = cachego.NewCache(cachego.WithAutoGC(10 * time.Minute))
// Also, you can add more than one option to cache.
cache = cachego.NewCache(cachego.WithAutoGC(10 * time.Minute), cachego.WithMapSize(64), cachego.WithSegmentSize(4096))
// Every option has its function, and you should use them for some purposes.
// WithDebugPoint runs a http server and registers some handlers for debug.
cachego.WithDebugPoint(":8888") // try to visit :8888
time.Sleep(time.Minute)
Index ¶
- Constants
- type Cache
- func (c *Cache) AutoGc(duration time.Duration) chan<- struct{}
- func (c *Cache) Gc()
- func (c *Cache) Get(key string) (interface{}, bool)
- func (c *Cache) GetWithLoad(key string, onMissed func() (data interface{}, ttl int64, err error)) (interface{}, error)
- func (c *Cache) Remove(key string)
- func (c *Cache) RemoveAll()
- func (c *Cache) Set(key string, value interface{})
- func (c *Cache) SetWithTTL(key string, value interface{}, ttl int64)
- func (c *Cache) Size() int
- type Option
Constants ¶
const (
// NeverDie means value.alive() returns true forever.
NeverDie = 0
)
const Version = "v0.2.2"
Version is the version string representation of cachego.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
Cache is a struct of cache.
func (*Cache) AutoGc ¶ added in v0.1.0
AutoGc starts a goroutine to execute Gc() at fixed duration. It returns a channel which can be used to stop this goroutine.
func (*Cache) Gc ¶
func (c *Cache) Gc()
Gc removes dead entries in Cache. Notice that this method is weak-consistency and it doesn't guarantee 100% removed.
func (*Cache) GetWithLoad ¶ added in v0.2.2
func (c *Cache) GetWithLoad(key string, onMissed func() (data interface{}, ttl int64, err error)) (interface{}, error)
GetWithLoad fetches value of key from c first, and returns it if ok. It will invoke onMissed() to fetch data and load it to c if missed. The unit of ttl is second.
func (*Cache) Remove ¶
Remove removes the value of key. If this key is not existed, nothing will happen.
func (*Cache) RemoveAll ¶
func (c *Cache) RemoveAll()
RemoveAll removes all keys in Cache. Notice that this method is weak-consistency.
func (*Cache) SetWithTTL ¶ added in v0.1.0
SetWithTTL sets key and value to Cache with a ttl. The unit of ttl is second.
type Option ¶ added in v0.2.1
type Option func(cache *Cache)
Option is a function which initializes cache.
func WithAutoGC ¶ added in v0.2.1
WithAutoGC is an option turning on automatically gc.
func WithDebugPoint ¶ added in v0.2.1
WithDebugPoint runs a http server and registers some handlers for debug. Don't use it in production!
func WithMapSize ¶ added in v0.2.1
WithMapSize is an option setting initializing map size of cache.
func WithSegmentSize ¶ added in v0.2.1
WithSegmentSize is an option setting initializing segment size of cache.
Source Files
Directories