cache2go

README

cache2go

Concurrency-safe golang caching library with expiration capabilities.

Installation

Make sure you have a working Go environment (Go 1.2 or higher is required). See the install instructions.

To install cache2go, simply run:

go get github.com/muesli/cache2go

To compile it from source:

cd $GOPATH/src/github.com/muesli/cache2go
go get -u -v
go build && go test -v

Example

package main

import (
	"github.com/muesli/cache2go"
	"fmt"
	"time"
)

// Keys & values in cache2go can be of arbitrary types, e.g. a struct.
type myStruct struct {
	text     string
	moreData []byte
}

func main() {
	// Accessing a new cache table for the first time will create it.
	cache := cache2go.Cache("myCache")

	// We will put a new item in the cache. It will expire after
	// not being accessed via Value(key) for more than 5 seconds.
	val := myStruct{"This is a test!", []byte{}}
	cache.Add("someKey", 5*time.Second, &val)

	// Let's retrieve the item from the cache.
	res, err := cache.Value("someKey")
	if err == nil {
		fmt.Println("Found value in cache:", res.Data().(*myStruct).text)
	} else {
		fmt.Println("Error retrieving value from cache:", err)
	}

	// Wait for the item to expire in cache.
	time.Sleep(6 * time.Second)
	res, err = cache.Value("someKey")
	if err != nil {
		fmt.Println("Item is not cached (anymore).")
	}

	// Add another item that never expires.
	cache.Add("someKey", 0, &val)

	// cache2go supports a few handy callbacks and loading mechanisms.
	cache.SetAboutToDeleteItemCallback(func(e *cache2go.CacheItem) {
		fmt.Println("Deleting:", e.Key(), e.Data().(*myStruct).text, e.CreatedOn())
	})

	// Remove the item from the cache.
	cache.Delete("someKey")

	// And wipe the entire cache table.
	cache.Flush()
}

To run this example, go to examples/mycachedapp/ and run:

go run mycachedapp.go

You can find a few more examples here. Also see our test-cases in cache_test.go for further working examples.

Documentation

Index

• Variables
• type CacheItem
  • func NewCacheItem(key interface{}, lifeSpan time.Duration, data interface{}) *CacheItem
  • func (item *CacheItem) AccessCount() int64
  • func (item *CacheItem) AccessedOn() time.Time
  • func (item *CacheItem) AddAboutToExpireCallback(f func(interface{}))
  • func (item *CacheItem) CreatedOn() time.Time
  • func (item *CacheItem) Data() interface{}
  • func (item *CacheItem) KeepAlive()
  • func (item *CacheItem) Key() interface{}
  • func (item *CacheItem) LifeSpan() time.Duration
  • func (item *CacheItem) RemoveAboutToExpireCallback()
  • func (item *CacheItem) SetAboutToExpireCallback(f func(interface{}))
• type CacheItemPair
• type CacheItemPairList
  • func (p CacheItemPairList) Len() int
  • func (p CacheItemPairList) Less(i, j int) bool
  • func (p CacheItemPairList) Swap(i, j int)
• type CacheTable
  • func Cache(table string) *CacheTable
  • func (table *CacheTable) Add(key interface{}, lifeSpan time.Duration, data interface{}) *CacheItem
  • func (table *CacheTable) AddAboutToDeleteItemCallback(f func(*CacheItem))
  • func (table *CacheTable) AddAddedItemCallback(f func(*CacheItem))
  • func (table *CacheTable) Count() int
  • func (table *CacheTable) Delete(key interface{}) (*CacheItem, error)
  • func (table *CacheTable) Exists(key interface{}) bool
  • func (table *CacheTable) Flush()
  • func (table *CacheTable) Foreach(trans func(key interface{}, item *CacheItem))
  • func (table *CacheTable) MostAccessed(count int64) []*CacheItem
  • func (table *CacheTable) NotFoundAdd(key interface{}, lifeSpan time.Duration, data interface{}) bool
  • func (table *CacheTable) RemoveAboutToDeleteItemCallback()
  • func (table *CacheTable) RemoveAddedItemCallbacks()
  • func (table *CacheTable) SetAboutToDeleteItemCallback(f func(*CacheItem))
  • func (table *CacheTable) SetAddedItemCallback(f func(*CacheItem))
  • func (table *CacheTable) SetDataLoader(f func(interface{}, ...interface{}) *CacheItem)
  • func (table *CacheTable) SetLogger(logger *log.Logger)
  • func (table *CacheTable) Value(key interface{}, args ...interface{}) (*CacheItem, error)

Variables

var (
	// ErrKeyNotFound gets returned when a specific key couldn't be found
	ErrKeyNotFound = errors.New("Key not found in cache")
	// ErrKeyNotFoundOrLoadable gets returned when a specific key couldn't be
	// found and loading via the data-loader callback also failed
	ErrKeyNotFoundOrLoadable = errors.New("Key not found and could not be loaded into cache")
)

Types

type CacheItem

type CacheItem struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

CacheItem is an individual cache item Parameter data contains the user-set value in the cache.

func NewCacheItem

func NewCacheItem(key interface{}, lifeSpan time.Duration, data interface{}) *CacheItem

NewCacheItem 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.

func (*CacheItem) AccessCount

func (item *CacheItem) AccessCount() int64

AccessCount returns how often this item has been accessed.

func (*CacheItem) AccessedOn

func (item *CacheItem) AccessedOn() time.Time

AccessedOn returns when this item was last accessed.

func (*CacheItem) AddAboutToExpireCallback

func (item *CacheItem) AddAboutToExpireCallback(f func(interface{}))

AddAboutToExpireCallback appends a new callback to the AboutToExpire queue

func (*CacheItem) CreatedOn

func (item *CacheItem) CreatedOn() time.Time

CreatedOn returns when this item was added to the cache.

func (*CacheItem) Data

func (item *CacheItem) Data() interface{}

Data returns the value of this cached item.

func (*CacheItem) KeepAlive

func (item *CacheItem) KeepAlive()

KeepAlive marks an item to be kept for another expireDuration period.

func (*CacheItem) Key

func (item *CacheItem) Key() interface{}

Key returns the key of this cached item.

func (*CacheItem) LifeSpan

func (item *CacheItem) LifeSpan() time.Duration

LifeSpan returns this item's expiration duration.

func (*CacheItem) RemoveAboutToExpireCallback

func (item *CacheItem) RemoveAboutToExpireCallback()

RemoveAboutToExpireCallback empties the about to expire callback queue

func (*CacheItem) SetAboutToExpireCallback

func (item *CacheItem) SetAboutToExpireCallback(f func(interface{}))

SetAboutToExpireCallback configures a callback, which will be called right before the item is about to be removed from the cache.

type CacheItemPair

type CacheItemPair struct {
	Key         interface{}
	AccessCount int64
}

CacheItemPair maps key to access counter

type CacheItemPairList

type CacheItemPairList []CacheItemPair

CacheItemPairList is a slice of CacheIemPairs that implements sort. Interface to sort by AccessCount.

func (CacheItemPairList) Len

func (p CacheItemPairList) Len() int

func (CacheItemPairList) Less

func (p CacheItemPairList) Less(i, j int) bool

func (CacheItemPairList) Swap

func (p CacheItemPairList) Swap(i, j int)

type CacheTable

type CacheTable struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

CacheTable is a table within the cache

func Cache

func Cache(table string) *CacheTable

Cache returns the existing cache table with given name or creates a new one if the table does not exist yet.

func (*CacheTable) Add

func (table *CacheTable) Add(key interface{}, lifeSpan time.Duration, data interface{}) *CacheItem

Add 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.

func (*CacheTable) AddAboutToDeleteItemCallback

func (table *CacheTable) AddAboutToDeleteItemCallback(f func(*CacheItem))

AddAboutToDeleteItemCallback appends a new callback to the AboutToDeleteItem queue

func (*CacheTable) AddAddedItemCallback

func (table *CacheTable) AddAddedItemCallback(f func(*CacheItem))

AddAddedItemCallback appends a new callback to the addedItem queue

func (*CacheTable) Count

func (table *CacheTable) Count() int

Count returns how many items are currently stored in the cache.

func (*CacheTable) Delete

func (table *CacheTable) Delete(key interface{}) (*CacheItem, error)

Delete an item from the cache.

func (*CacheTable) Exists

func (table *CacheTable) Exists(key interface{}) bool

Exists returns 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 (*CacheTable) Flush

func (table *CacheTable) Flush()

Flush deletes all items from this cache table.

func (*CacheTable) Foreach

func (table *CacheTable) Foreach(trans func(key interface{}, item *CacheItem))

Foreach all items

func (*CacheTable) MostAccessed

func (table *CacheTable) MostAccessed(count int64) []*CacheItem

MostAccessed returns the most accessed items in this cache table

func (*CacheTable) NotFoundAdd

func (table *CacheTable) NotFoundAdd(key interface{}, lifeSpan time.Duration, data interface{}) bool

NotFoundAdd checks whether an item is not yet cached. Unlike the Exists method this also adds data if the key could not be found.

func (*CacheTable) RemoveAboutToDeleteItemCallback

func (table *CacheTable) RemoveAboutToDeleteItemCallback()

RemoveAboutToDeleteItemCallback empties the about to delete item callback queue

func (*CacheTable) RemoveAddedItemCallbacks

func (table *CacheTable) RemoveAddedItemCallbacks()

RemoveAddedItemCallbacks empties the added item callback queue

func (*CacheTable) SetAboutToDeleteItemCallback

func (table *CacheTable) SetAboutToDeleteItemCallback(f func(*CacheItem))

SetAboutToDeleteItemCallback configures a callback, which will be called every time an item is about to be removed from the cache.

func (*CacheTable) SetAddedItemCallback

func (table *CacheTable) SetAddedItemCallback(f func(*CacheItem))

SetAddedItemCallback configures a callback, which will be called every time a new item is added to the cache.

func (*CacheTable) SetDataLoader

func (table *CacheTable) SetDataLoader(f func(interface{}, ...interface{}) *CacheItem)

SetDataLoader 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.

func (*CacheTable) SetLogger

func (table *CacheTable) SetLogger(logger *log.Logger)

SetLogger sets the logger to be used by this cache table.

func (*CacheTable) Value

func (table *CacheTable) Value(key interface{}, args ...interface{}) (*CacheItem, error)

Value returns an item from the cache and marks it to be kept alive. You can pass additional arguments to your DataLoader callback function.