Go缓存库cache2go源码阅读
2017-06-06 16:20
309 查看
项目地址：
https://github.com/muesli/cache2go/blob/master/README.md项目介绍
cache2go:一个并发安全，具有心跳功能的缓存库。核心功能只有3个文件。从中可以学习到，go语言中的锁、goroutine、map操作等。
主要特性如下：
1. 并发安全
2. 可设置缓存项的生命周期
3. 可设置缓存清理周期
4. 包含缓存增加、删除的回调函数
5. 包含单条缓存以及缓存表
源码阅读
代码量比较少，我在关键的地方都添加了注释，就直接贴代码了。英文水平有限有翻译不对的地方请多多指教。cacheItem.go文件
单个缓存package cache2go
import (
"sync"
"time"
)
// Structure of an item in the cache.
// Parameter data contains the user-set value in the cache.
type CacheItem struct {
sync.RWMutex //读写锁
// The item's key.
// 缓存项的key.
key interface{}
// The item's data.
// 缓存项的值
data interface{}
// How long will the item live in the cache when not being accessed/kept alive.
// 缓存项的生命期
lifeSpan time.Duration
// Creation timestamp.
// 创建时间
createdOn time.Time
// Last access timestamp.
// 最后访问时间
accessedOn time.Time
// How often the item was accessed.
// 访问次数
accessCount int64
// Callback method triggered right before removing the item from the cache
// 在删除缓存项之前调用的回调函数
aboutToExpire func(key interface{})
}
// Returns a newly created CacheItem.
// Parameter key is the item's cache-key.
// Parameter lifeSpan determines after which time period without an access the item
// will get removed from the cache.
// Parameter data is the item's value.
// CreateCacheItem返回一个新创建的CacheItem。
// 参数key是cache-key。
// 参数lifeSpan(生命周期)，确定在没有访问该项目的时间段后将从缓存中移除
// 参数data是项目中的值
func CreateCacheItem(key interface{}, lifeSpan time.Duration, data interface{}) CacheItem {
t := time.Now()
return CacheItem{
key: key,
lifeSpan: lifeSpan,
createdOn: t,
accessedOn: t,
accessCount: 0,
aboutToExpire: nil,
data: data,
}
}
// Mark item to be kept for another expireDuration period.
// KeepAlive标记一个项目保持另一个expireDuration（持续时间）周期
func (item *CacheItem) KeepAlive() {
item.Lock()
defer item.Unlock()
item.accessedOn = time.Now()
item.accessCount++
}
// Returns this item's expiration duration.
// LifeSpan 返回项目的心跳时间（终结周期）
func (item *CacheItem) LifeSpan() time.Duration {
// immutable
return item.lifeSpan
}
// Returns when this item was last accessed.
// AccessedOn返回项目最后被访问的时间
func (item *CacheItem) AccessedOn() time.Time {
item.RLock()
defer item.RUnlock()
return item.accessedOn
}
// Returns when this item was added to the cache.
// CreatedOn返回项目被加入缓存的时间
func (item *CacheItem) CreatedOn() time.Time {
// immutable
return item.createdOn
}
// Returns how often this item has been accessed.
// AccessCount返回这个项目被访问次数
func (item *CacheItem) AccessCount() int64 {
item.RLock()
defer item.RUnlock()
return item.accessCount
}
// Returns the key of this cached item.
// 返回缓存中的key
func (item *CacheItem) Key() interface{} {
// immutable
return item.key
}
// Returns the value of this cached item.
// Data返回这个项目的值
func (item *CacheItem) Data() interface{} {
// immutable
return item.data
}
// Configures a callback, which will be called right before the item
// is about to be removed from the cache.
// setabouttoexpirecallback配置回调,在项目删除之前调用
func (item *CacheItem) SetAboutToExpireCallback(f func(interface{})) {
item.Lock()
defer item.Unlock()
item.aboutToExpire = f
}从结构体中我们可以看到key与data都是interface{}类型，即可以传任意类型，但是建议key为可比较的类型。
lifeSpan time.Duration 可设置生命周期，以及创建时间，访问次数等记录，以及添加了注释这里就不详细的描述了。
cacheTable.go文件
缓存表package cache2go
import (
"log"
"sort"
"sync"
"time"
)
// Structure of a table with items in the cache.
type CacheTable struct {
sync.RWMutex
// The table's name.
// 缓存表名
name string
// All cached items.
// 缓存项
items map[interface{}]*CacheItem
// Timer responsible for triggering cleanup.
// 触发缓存清理的定时器
cleanupTimer *time.Timer
// Current timer duration.
// 缓存清理周期
cleanupInterval time.Duration
// The logger used for this table.
// 该缓存表的日志
logger *log.Logger
// Callback method triggered when trying to load a non-existing key.
// 获取一个不存在的缓存项时的回调函数
loadData func(key interface{}, args ...interface{}) *CacheItem
// Callback method triggered when adding a new item to the cache.
// 向缓存表增加缓存项时的回调函数
addedItem func(item *CacheItem)
// Callback method triggered before deleting an item from the cache.
// 从缓存表删除一个缓存项时的回调函数
aboutToDeleteItem func(item *CacheItem)
}
// Returns how many items are currently stored in the cache.
// 返回当缓存中存储有多少项
func (table *CacheTable) Count() int {
table.RLock()
defer table.RUnlock()
return len(table.items)
}
// foreach all items
// Foreach所有项目
func (table *CacheTable) Foreach(trans func(key interface{}, item *CacheItem)) {
table.RLock()
defer table.RUnlock()
for k, v := range table.items {
trans(k, v)
}
}
// Configures a data-loader callback, which will be called when trying
// to access a non-existing key. The key and 0...n additional arguments
// are passed to the callback function.
// SetDataLoader配置一个数据加载的回调，当尝试去请求一个不存在的key的时候调用
func (table *CacheTable) SetDataLoader(f func(interface{}, ...interface{}) *CacheItem) {
table.Lock()
defer table.Unlock()
table.loadData = f
}
// Configures a callback, which will be called every time a new item
// is added to the cache.
// SetAddedItemCallback配置一个回调，当向缓存中添加项目时每次都会被调用
func (table *CacheTable) SetAddedItemCallback(f func(*CacheItem)) {
table.Lock()
defer table.Unlock()
table.addedItem = f
}
// Configures a callback, which will be called every time an item
// is about to be removed from the cache.
// setabouttodeleteitemcallback配置一个回调，当一个项目从缓存中删除时每次都会被调用
func (table *CacheTable) SetAboutToDeleteItemCallback(f func(*CacheItem)) {
table.Lock()
defer table.Unlock()
table.aboutToDeleteItem = f
}
// Sets the logger to be used by this cache table.
// 设置缓存表需要使用的log
func (table *CacheTable) SetLogger(logger *log.Logger) {
table.Lock()
defer table.Unlock()
table.logger = logger
}
//终结检查，被自调整的时间触发
// Expiration check loop, triggered by a self-adjusting timer.
func (table *CacheTable) expirationCheck() {
table.Lock()
if table.cleanupTimer != nil {
table.cleanupTimer.Stop()
}
if table.cleanupInterval > 0 {
table.log("Expiration check triggered after", table.cleanupInterval, "for table", table.name)
} else {
table.log("Expiration check installed for table", table.name)
}
// Cache value so we don't keep blocking the mutex.
items := table.items
table.Unlock()
// To be more accurate with timers, we would need to update 'now' on every
// loop iteration. Not sure it's really efficient though.
//为了定时器更准确，我们需要在每一个循环中更新‘now’，不确定是否是有效率的。
now := time.Now()
smallestDuration := 0 * time.Second
for key, item := range items {
// Cache values so we don't keep blocking the mutex.
item.RLock()
lifeSpan := item.lifeSpan
accessedOn := item.accessedOn
item.RUnlock()
if lifeSpan == 0 { // 0永久有效
continue
}
if now.Sub(accessedOn) >= lifeSpan {
// Item has excessed its lifespan.//项目已经超过了项目周期
table.Delete(key)
} else {
// Find the item chronologically closest to its end-of-lifespan.
//查找最靠近结束生命周期的项目
if smallestDuration == 0 || lifeSpan-now.Sub(accessedOn) < smallestDuration {
smallestDuration = lifeSpan - now.Sub(accessedOn)
}
}
}
// Setup the interval for the next cleanup run.
// 为下次清理设置间隔
table.Lock()
table.cleanupInterval = smallestDuration
if smallestDuration > 0 {
table.cleanupTimer = time.AfterFunc(smallestDuration, func() {
go table.expirationCheck()
})
}
table.Unlock()
}
// Adds a key/value pair to the cache.
// Parameter key is the item's cache-key.
// Parameter lifeSpan determines after which time period without an access the item
// will get removed from the cache.
// Parameter data is the item's value.
// 添加键值对到缓存中
// 参数key是cache-key。
// 参数lifeSpan(生命周期)，确定在没有访问该项目的时间段后将从缓存中移除
// 参数data是项目中的值
func (table *CacheTable) Add(key interface{}, lifeSpan time.Duration, data interface{}) *CacheItem {
item := CreateCacheItem(key, lifeSpan, data)
// Add item to cache.
table.Lock()
table.log("Adding item with key", key, "and lifespan of", lifeSpan, "to table", table.name)
table.items[key] = &item
// Cache values so we don't keep blocking the mutex.
expDur := table.cleanupInterval
addedItem := table.addedItem
table.Unlock()
// Trigger callback after adding an item to cache.
if addedItem != nil {
addedItem(&item)
}
// If we haven't set up any expiration check timer or found a more imminent item.
// 如果我们没有设置任何心跳检查定时器或者找一个即将迫近的项目
if lifeSpan > 0 && (expDur == 0 || lifeSpan < expDur) {
table.expirationCheck()
}
return &item
}
// Delete an item from the cache.
// 从缓存中删除项
func (table *CacheTable) Delete(key interface{}) (*CacheItem, error) {
table.RLock()
r, ok := table.items[key]
if !ok {
table.RUnlock()
return nil, ErrKeyNotFound
}
// Cache value so we don't keep blocking the mutex.
aboutToDeleteItem := table.aboutToDeleteItem
table.RUnlock()
// Trigger callbacks before deleting an item from cache.
if aboutToDeleteItem != nil {
aboutToDeleteItem(r)
}
r.RLock()
defer r.RUnlock()
if r.aboutToExpire != nil {
r.aboutToExpire(key)
}
table.Lock()
defer table.Unlock()
table.log("Deleting item with key", key, "created on", r.createdOn, "and hit", r.accessCount, "times from table", table.name)
delete(table.items, key)
return r, nil
}
// Test whether an item exists in the cache. Unlike the Value method
// Exists neither tries to fetch data via the loadData callback nor
// does it keep the item alive in the cache.
// 返回项目是否在缓存中。不像这个数据方法，既不尝试渠道数据本地的回调也不保证项目在缓存中是存活的。
func (table *CacheTable) Exists(key interface{}) bool {
table.RLock()
defer table.RUnlock()
_, ok := table.items[key]
return ok
}
// Test whether an item not found in the cache. Unlike the Exists method
// NotExistsAdd also add data if not found.
// NotFoundAdd测试是否一个项目不存在在缓存中。不像是已经存在的方法，当key不存在时依旧添加。
func (table *CacheTable) NotFoundAdd(key interface{}, lifeSpan time.Duration, data interface{}) bool {
table.Lock()
if _, ok := table.items[key]; ok {
table.Unlock()
return false
}
item := CreateCacheItem(key, lifeSpan, data)
table.log("Adding item with key", key, "and lifespan of", lifeSpan, "to table", table.name)
table.items[key] = &item
// Cache values so we don't keep blocking the mutex.
expDur := table.cleanupInterval
addedItem := table.addedItem
table.Unlock()
// Trigger callback after adding an item to cache.
if addedItem != nil {
addedItem(&item)
}
// If we haven't set up any expiration check timer or found a more imminent item.
if lifeSpan > 0 && (expDur == 0 || lifeSpan < expDur) {
table.expirationCheck()
}
return true
}
// Get an item from the cache and mark it to be kept alive. You can pass
// additional arguments to your DataLoader callback function.
//从缓存中返回一个被标记的并保持活性的值。你可以传附件的参数到DataLoader回调函数
func (table *CacheTable) Value(key interface{}, args ...interface{}) (*CacheItem, error) {
table.RLock()
r, ok := table.items[key]
loadData := table.loadData
table.RUnlock()
if ok {
// Update access counter and timestamp.
r.KeepAlive()
return r, nil
}
// Item doesn't exist in cache. Try and fetch it with a data-loader.
if loadData != nil {
item := loadData(key, args...)
if item != nil {
table.Add(key, item.lifeSpan, item.data)
return item, nil
}
return nil, ErrKeyNotFoundOrLoadable
}
return nil, ErrKeyNotFound
}
// Delete all items from cache.
// 删除缓存表中的所有项目
func (table *CacheTable) Flush() {
table.Lock()
defer table.Unlock()
table.log("Flushing table", table.name)
table.items = make(map[interface{}]*CacheItem)
table.cleanupInterval = 0
if table.cleanupTimer != nil {
table.cleanupTimer.Stop()
}
}
type CacheItemPair struct {
Key interface{}
AccessCount int64
}
// A slice of CacheIemPairs that implements sort. Interface to sort by AccessCount.
// CacheItemPairList是CacheIemPairs的一个排序后的切片，interface依据请求次数排序
type CacheItemPairList []CacheItemPair
func (p CacheItemPairList) Swap(i, j int) { p[i], p[j] = p[j], p[i] }
func (p CacheItemPairList) Len() int { return len(p) }
func (p CacheItemPairList) Less(i, j int) bool { return p[i].AccessCount > p[j].AccessCount }
// 返回缓存表中被访问最多的项目
func (table *CacheTable) MostAccessed(count int64) []*CacheItem {
table.RLock()
defer table.RUnlock()
p := make(CacheItemPairList, len(table.items))
i := 0
for k, v := range table.items {
p[i] = CacheItemPair{k, v.accessCount}
i++
}
sort.Sort(p)
var r []*CacheItem
c := int64(0)
for _, v := range p {
if c >= count {
break
}
item, ok := table.items[v.Key]
if ok {
r = append(r, item)
}
c++
}
return r
}
// Internal logging method for convenience.
func (table *CacheTable) log(v ...interface{}) {
if table.logger == nil {
return
}
table.logger.Println(v)
}结构体中我们可以看出缓存项为一个map，并存在指定得表名中(name)中，cleanupTimer与cleanupInterval控制清理缓存。以及三个回调函数。并提供了增加、删除、查找、遍历、刷新等操作这里就不一一介绍了。
其中比较特殊的就是缓存清理周期。主要代码在expirationCheck函数中实现。代码会遍历所有缓存项，为了保证计时器的准确性每次循环都会更新，这里可以看出生命周期设置为‘0’代表永久有效，找到过期的项删除，然后找到即将要过期项的时间用作cleanupInterval(缓存周期)，即下一次缓存更新的时间。以此方式实现自调节。此处只是说了代码实现的大概，觉得不清楚的可以看代码添加了详细的注释。
cache2go
package cache2go
import (
"sync"
)
var (
cache = make(map[string]*CacheTable)
mutex sync.RWMutex
)
// Returns the existing cache table with given name or creates a new one
// if the table does not exist yet.
// 返回现有的缓存表与给定的名称，如果表不存在创建一个新的
func Cache(table string) *CacheTable {
mutex.RLock()
t, ok := cache