cachego

README

📜 cachego

cachego 是一个拥有高性能分段锁机制的轻量级内存缓存，拥有懒清理和哨兵清理两种清理机制，可以应用于所有的 GoLang 应用程序中。

Read me in English.

🕹 功能特性

• 以键值对形式缓存数据，极简的 API 设计风格
• 使用粒度更细的分段锁机制进行设计，具有非常高的并发性能
• 支持懒清理机制，每一次访问的时候判断是否过期
• 支持哨兵清理机制，每隔一定的时间间隔进行清理

历史版本的特性请查看 HISTORY.md。未来版本的新特性和计划请查看 FUTURE.md。

🚀 安装方式

cachego 没有任何其他额外的依赖，唯一需要的依赖就是 Golang 运行环境。

$ go get -u github.com/FishGoddess/cachego

💡 参考案例

package main

import (
	"fmt"

	"github.com/FishGoddess/cachego"
)

func main() {

	// Create a cache for use.
	cache := cachego.NewCache()

	// 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 want to change the value of a key, just set a new value of this key.
	cache.Set("key", "value")

	// See what value it has.
	v, ok = cache.Get("key")
	fmt.Println(v, ok) // Output: value 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
}

更多使用案例请查看 _examples 目录。

🔥 性能测试

测试文件：_examples/performance_test.go

$ 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 算法的优化建议

如果您觉得 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.
cache := cachego.NewCache()

// 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 want to change the value of a key, just set a new value of this key.
cache.Set("key", "value")

// See what value it has.
v, ok = cache.Get("key")
fmt.Println(v, ok) // Output: value 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

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

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 <-chan type 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 <- true

Index

• Constants
• type Cache
  • func NewCache() *Cache
  • func (c *Cache) AutoGc(duration time.Duration) chan<- bool
  • func (c *Cache) Gc()
  • func (c *Cache) Get(key string) (interface{}, bool)
  • 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

Constants

const (
	// NeverDie means value.alive() returns true forever.
	NeverDie = 0
)

const Version = "v0.1.3"

Version is the version string representation of cachego.

Types

type Cache

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

Cache is a struct of cache.

func NewCache

func NewCache() *Cache

NewCache returns a new Cache holder for use.

func (*Cache) AutoGc

func (c *Cache) AutoGc(duration time.Duration) chan<- bool

AutoGc starts a goroutine to execute Gc() at fixed duration. It returns a <-chan type 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) Get

func (c *Cache) Get(key string) (interface{}, bool)

Get returns the value of key and a false if not found.

func (*Cache) Remove

func (c *Cache) Remove(key string)

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) Set

func (c *Cache) Set(key string, value interface{})

Set sets key and value to Cache. The key will not expire.

func (*Cache) SetWithTTL

func (c *Cache) SetWithTTL(key string, value interface{}, ttl int64)

SetWithTTL sets key and value to Cache with a ttl.

func (*Cache) Size

func (c *Cache) Size() int

Size returns the size of Cache. Notice that this method is weak-consistency.