Go緩存庫cache2go源碼閱讀

項目地址：

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[table]
    mutex.RUnlock()

    if !ok {
        t = &CacheTable{
            name:  table,
            items: make(map[interface{}]*CacheItem),
        }

        mutex.Lock()
        cache[table] = t
        mutex.Unlock()
    }

    return t
}

首先判斷map中是否包含緩存表，沒有就創建一個。

使用示例

使用示例共包含了基本使用方法（mycachedapp.go），回調使用方法（callbacks.go），dataloader回調使用（dataloader.go）。這裏就不貼代碼了，大家可以下載源碼查看。

總結

代碼量不大很適合學習，閱讀完之後又想到了好多問題，一個個解決吧。