cache2go

README

cache2go

Simple golang object caching library with expiration capabilities.

Installation

Make sure you have a working Go environment. See the install instructions.

To install cache2go, simply run:

go get github.com/muesli/cache2go

To compile it from source:

git clone git://github.com/muesli/cache2go.git
cd cache2go && go build && go test -v

Example

package main

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

// Keys & values in cache2go can be off 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.

Development

API docs can be found here.

Continuous integration:

Documentation

Index

• Variables
• type CacheItem
  • func CreateCacheItem(key interface{}, lifeSpan time.Duration, data interface{}) CacheItem
  • func (item *CacheItem) AccessCount() int64
  • func (item *CacheItem) AccessedOn() time.Time
  • 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) 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) 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) 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           = errors.New("Key not found in cache")
	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
}

Structure of an item in the cache. Parameter data contains the user-set value in the cache.

func CreateCacheItem

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

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

Returns how often this item has been accessed.

func (*CacheItem) AccessedOn

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

Returns when this item was last accessed.

func (*CacheItem) CreatedOn

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

Returns when this item was added to the cache.

func (*CacheItem) Data

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

Returns the value of this cached item.

func (*CacheItem) KeepAlive

func (item *CacheItem) KeepAlive()

Mark item to be kept for another expireDuration period.

func (*CacheItem) Key

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

Returns the key of this cached item.

func (*CacheItem) LifeSpan

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

Returns this item's expiration duration.

func (*CacheItem) SetAboutToExpireCallback

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

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
}

type CacheItemPairList

type CacheItemPairList []CacheItemPair

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
}

Structure of a table with items in the cache.

func Cache

func Cache(table string) *CacheTable

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

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) Count

func (table *CacheTable) Count() int

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

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

func (table *CacheTable) Flush()

Delete all items from cache.

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

func (*CacheTable) NotFoundAdd

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

Test whether an item not found in the cache. Unlike the Exists method NotExistsAdd also add data if not found.

func (*CacheTable) SetAboutToDeleteItemCallback

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

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))

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)

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)

Sets the logger to be used by this cache table.

func (*CacheTable) Value

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

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