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-4700U CPU @ 2.0 GHZ，16 GB RAM

测试	写入消耗时间 (越小越好)	读取消耗时间 (越小越好)	综合消耗时间 (越小越好)
cachego	3.51 秒	2.93 秒	2.97 秒
go-cache	5.73 秒	2.19 秒	9.78 秒
freeCache	2.43 秒	2.09 秒	2.58 秒

可以看出，由于使用了分段锁机制，写入性能在并发下依然非常高，但是读取性能有些拉跨，这是由于分段锁会多一次定位的操作，如果加锁的消耗小于定位的消耗，那分段锁就不占优势。 这也是为什么 cachego 在写入性能上比 go-cache 强一大截，但是读取性能却落后的原因。后续会着重优化读取性能！

👥 贡献者

如果您觉得 cachego 缺少您需要的功能，请不要犹豫，马上参与进来，发起一个 issue。

Documentation

Overview

Copyright 2020 Ye Zi Jie. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Author: FishGoddess Email: fishgoddess@qq.com Created at 2020/03/14 16:28:56

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

Copyright 2020 Ye Zi Jie. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Author: FishGoddess Email: fishgoddess@qq.com Created at 2020/09/11 00:19:07

Copyright 2020 Ye Zi Jie. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Author: FishGoddess Email: fishgoddess@qq.com Created at 2020/03/14 14:43:24

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.0"

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.