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/rif/cache2go

To compile it from source:

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

Example

package main

import (
	"github.com/rif/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.Cache("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.Cache("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 the application, 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.

Continous integration:

Documentation

Index

• 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 CacheTable
  • func Cache(table string) *CacheTable
  • func (table *CacheTable) Cache(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) SetAboutToDeleteItemCallback(f func(*CacheItem))
  • func (table *CacheTable) SetAddedItemCallback(f func(*CacheItem))
  • func (table *CacheTable) SetDataLoader(f func(interface{}) *CacheItem)
  • func (table *CacheTable) SetLogger(logger *log.Logger)
  • func (table *CacheTable) Value(key interface{}) (*CacheItem, error)

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

func (table *CacheTable) Cache(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) 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{}) *CacheItem)

Configures a data-loader callback, which will be called when trying to use access a non-existing key.

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{}) (*CacheItem, error)

Get an item from the cache and mark it to be kept alive.