rw_freecache

README

rw_freecache

感谢 freecache 原作者对代码的无私贡献和其他开发者对代码的改善付出的卓越的努力。

设计初心：

freecache 因为其高效的性能获得很多人的喜爱，我也不例外。却因为里面使用了go Mutex导致了在非常高的并发情况下性能无法进一步提高，主要原因就是使用 get 方法中的Mutex.Lock()。 通过跟原作者的沟通后，发现因为 freecache get方法并不是只读方法，所以才动了念头修改一版能够满足自己高并发http平台的cache。

特性 （相比原 freecache）：

1. 将Mutex 修改成 RWMutex --> 并发性能极大的提高
2. 去掉了segment访问时间计数器，重新添加平局访问计数器。（在 GetSummaryStatus 方法的返回值中）

性能测试 （performance）CPU:i5 4590 ：

BenchmarkMapSet-4                           	 2000000	       634 ns/op
BenchmarkCacheSet-4                         	 5000000	       407 ns/op
BenchmarkCacheSetParallel-4                 	10000000	       369 ns/op
BenchmarkMapGet-4                           	20000000	       165 ns/op
BenchmarkCacheGet-4                         	 5000000	       398 ns/op
BenchmarkCacheGetParallel-4                 	20000000	        89.8 ns/op
BenchmarkCacheGetWithExpiration-4           	 5000000	       459 ns/op
BenchmarkCacheGetWithExpirationParallel-4   	20000000	        83.1 ns/op
BenchmarkHashFunc-4                         	200000000	         7.29 ns/op

使用例子： （和原 freecache 没有区别）

cacheSize := 100 * 1024 * 1024  // 100M
cache := freecache.NewCache(cacheSize)
debug.SetGCPercent(20)

key := []byte("abc")
val := []byte("def")
expire := 60 // expire in 60 seconds

cache.Set(key, val, expire)

got, err := cache.Get(key)
if err != nil {
    fmt.Println(err)
} else {
    fmt.Println(string(got))
}

affected := cache.Del(key)

fmt.Println("deleted key ", affected)
fmt.Println("entry count ", cache.EntryCount())

Documentation

Index

• Constants
• Variables
• type Cache
  • func NewCache(size int) (cache *Cache)
  • func (cache *Cache) Clear()
  • func (cache *Cache) Del(key []byte) (affected bool)
  • func (cache *Cache) DelInt(key int64) bool
  • func (cache *Cache) DelStr(key string) bool
  • func (cache *Cache) EntryCount() (entryCount int64)
  • func (cache *Cache) EvacuateCount() (count int64)
  • func (cache *Cache) ExpiredCount() (count int64)
  • func (cache *Cache) Get(key []byte) (value []byte, err error)
  • func (cache *Cache) GetInt(key int64) ([]byte, error)
  • func (cache *Cache) GetIntWithExpiration(key int64) ([]byte, uint32, error)
  • func (cache *Cache) GetStr(key string) ([]byte, error)
  • func (cache *Cache) GetStrWithExpiration(key string) ([]byte, uint32, error)
  • func (cache *Cache) GetSummaryStatus() CacheSummaryStatus
  • func (cache *Cache) GetWithExpiration(key []byte) (value []byte, expireAt uint32, err error)
  • func (cache *Cache) HitCount() (count int64)
  • func (cache *Cache) HitRate() float64
  • func (cache *Cache) LookupCount() int64
  • func (cache *Cache) MissCount() (count int64)
  • func (cache *Cache) NewIterator() *Iterator
  • func (cache *Cache) OverwriteCount() (overwriteCount int64)
  • func (cache *Cache) ResetStatistics()
  • func (cache *Cache) Set(key, value []byte, expireSeconds int) (err error)
  • func (cache *Cache) SetInt(key int64, value []byte, expireSeconds int) error
  • func (cache *Cache) SetStr(key string, value []byte, expireSeconds int) error
  • func (cache *Cache) SetStrEx(key, value string, expireSeconds int) error
  • func (cache *Cache) TTL(key []byte) (timeLeft uint32, err error)
  • func (cache *Cache) TTLInt(key int64) (uint32, error)
  • func (cache *Cache) TTLStr(key string) (uint32, error)
• type CacheSummaryStatus
• type Entry
• type Iterator
  • func (it *Iterator) Next() *Entry
• type RingBuf
  • func NewRingBuf(size int, begin int64) (rb RingBuf)
  • func (rb *RingBuf) Begin() int64
  • func (rb *RingBuf) Dump() []byte
  • func (rb *RingBuf) End() int64
  • func (rb *RingBuf) EqualAt(p []byte, off int64) bool
  • func (rb *RingBuf) Evacuate(off int64, length int) (newOff int64)
  • func (rb *RingBuf) ReadAt(p []byte, off int64) (n int, err error)
  • func (rb *RingBuf) Resize(newSize int)
  • func (rb *RingBuf) Size() int64
  • func (rb *RingBuf) Skip(length int64)
  • func (rb *RingBuf) String() string
  • func (rb *RingBuf) ToJSON() string
  • func (rb *RingBuf) Write(p []byte) (n int, err error)
  • func (rb *RingBuf) WriteAt(p []byte, off int64) (n int, err error)

Constants

const (
	ENTRY_HDR_SIZE = 24
)

Variables

var ErrLargeCounterValue = errors.New(fmt.Sprintf("The counter value is larger than %d", maxSegmentItemCount))

var ErrLargeEntry = errors.New("The entry size is larger than 1/1024 of cache size")

var ErrLargeKey = errors.New("The key is larger than 65535")

var ErrNotFound = errors.New("Entry not found")

var ErrOutOfRange = errors.New("Out of range")

Types

type Cache

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

func NewCache

func NewCache(size int) (cache *Cache)

The cache size will be set to 512KB at minimum. If the size is set relatively large, you should call `debug.SetGCPercent()`, set it to a much smaller value to limit the memory consumption and GC pause time.

func (*Cache) Clear

func (cache *Cache) Clear()

func (*Cache) Del

func (cache *Cache) Del(key []byte) (affected bool)

func (*Cache) DelInt

func (cache *Cache) DelInt(key int64) bool

func (*Cache) DelStr

func (cache *Cache) DelStr(key string) bool

func (*Cache) EntryCount

func (cache *Cache) EntryCount() (entryCount int64)

func (*Cache) EvacuateCount

func (cache *Cache) EvacuateCount() (count int64)

func (*Cache) ExpiredCount

func (cache *Cache) ExpiredCount() (count int64)

func (*Cache) Get

func (cache *Cache) Get(key []byte) (value []byte, err error)

Get the value or not found error.

func (*Cache) GetInt

func (cache *Cache) GetInt(key int64) ([]byte, error)

func (*Cache) GetIntWithExpiration

func (cache *Cache) GetIntWithExpiration(key int64) ([]byte, uint32, error)

func (*Cache) GetStr

func (cache *Cache) GetStr(key string) ([]byte, error)

func (*Cache) GetStrWithExpiration

func (cache *Cache) GetStrWithExpiration(key string) ([]byte, uint32, error)

func (*Cache) GetSummaryStatus

func (cache *Cache) GetSummaryStatus() CacheSummaryStatus

func (*Cache) GetWithExpiration

func (cache *Cache) GetWithExpiration(key []byte) (value []byte, expireAt uint32, err error)

Get the value or not found error.

func (*Cache) HitCount

func (cache *Cache) HitCount() (count int64)

func (*Cache) HitRate

func (cache *Cache) HitRate() float64

func (*Cache) LookupCount

func (cache *Cache) LookupCount() int64

func (*Cache) MissCount

func (cache *Cache) MissCount() (count int64)

func (*Cache) NewIterator

func (cache *Cache) NewIterator() *Iterator

NewIterator creates a new iterator for the cache.

func (*Cache) OverwriteCount

func (cache *Cache) OverwriteCount() (overwriteCount int64)

func (*Cache) ResetStatistics

func (cache *Cache) ResetStatistics()

func (*Cache) Set

func (cache *Cache) Set(key, value []byte, expireSeconds int) (err error)

If the key is larger than 65535 or value is larger than 1/1024 of the cache size, the entry will not be written to the cache. expireSeconds <= 0 means no expire, but it can be evicted when cache is full.

func (*Cache) SetInt

func (cache *Cache) SetInt(key int64, value []byte, expireSeconds int) error

func (*Cache) SetStr

func (cache *Cache) SetStr(key string, value []byte, expireSeconds int) error

func (*Cache) SetStrEx

func (cache *Cache) SetStrEx(key, value string, expireSeconds int) error

func (*Cache) TTL

func (cache *Cache) TTL(key []byte) (timeLeft uint32, err error)

func (*Cache) TTLInt

func (cache *Cache) TTLInt(key int64) (uint32, error)

func (*Cache) TTLStr

func (cache *Cache) TTLStr(key string) (uint32, error)

type CacheSummaryStatus

type CacheSummaryStatus struct {
	TimeStamp            int64   //时间片
	TimeSlice            int64   //时间段 (两次读取之间的时间间隔)
	ItemsCount           int64   //缓存中对象数量
	ItemsHitRate         float64 //缓存对象命中率
	AvgAccessTime        float64 //缓存对象平均访问时间
	AvgLookupPerSecond   float64 //缓存每秒查询多少次
	AvgHitPerSecond      float64 //缓存每秒击中对象多少次
	AvgExpiredPerSecond  float64 //缓存每秒超时多少个对象
	AvgEvacuatePerSecond float64 //缓存每秒因为空间不够导致清理的次数 (如果太大表示创建缓存的空间不够)
	// contains filtered or unexported fields
}

type Entry

type Entry struct {
	Key   []byte
	Value []byte
}

Entry represents a key/value pair.

type Iterator

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

Iterator iterates the entries for the cache.

func (*Iterator) Next

func (it *Iterator) Next() *Entry

Next returns the next entry for the iterator. The order of the entries is not guaranteed. If there is no more entries to return, nil will be returned.

type RingBuf

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

Ring buffer has a fixed size, when data exceeds the size, old data will be overwritten by new data. It only contains the data in the stream from begin to end

func NewRingBuf

func NewRingBuf(size int, begin int64) (rb RingBuf)

func (*RingBuf) Begin

func (rb *RingBuf) Begin() int64

func (*RingBuf) Dump

func (rb *RingBuf) Dump() []byte

Create a copy of the buffer.

func (*RingBuf) End

func (rb *RingBuf) End() int64

func (*RingBuf) EqualAt

func (rb *RingBuf) EqualAt(p []byte, off int64) bool

func (*RingBuf) Evacuate

func (rb *RingBuf) Evacuate(off int64, length int) (newOff int64)

Evacuate read the data at off, then write it to the the data stream, Keep it from being overwritten by new data.

func (*RingBuf) ReadAt

func (rb *RingBuf) ReadAt(p []byte, off int64) (n int, err error)

read up to len(p), at off of the data stream.

func (*RingBuf) Resize

func (rb *RingBuf) Resize(newSize int)

func (*RingBuf) Size

func (rb *RingBuf) Size() int64

func (*RingBuf) Skip

func (rb *RingBuf) Skip(length int64)

func (*RingBuf) String

func (rb *RingBuf) String() string

func (*RingBuf) ToJSON

func (rb *RingBuf) ToJSON() string

func (*RingBuf) Write

func (rb *RingBuf) Write(p []byte) (n int, err error)

func (*RingBuf) WriteAt

func (rb *RingBuf) WriteAt(p []byte, off int64) (n int, err error)