ltcache

README

LRU/TTL Cache system written in Go

Some of it's properties:

• Both LRU or TTL enforcements are optional and independent of each other.
• Thread safe through the use of unique lock, making each operation atomic.
• TTL refresh on get/set optional through the use of static setting.
• Item groups for groupped remove
• Transactional if TransCache is used
• Multiple instances if TransCache is used

Installation

go get github.com/cgrates/ltcache

Support

Join CGRateS on Google Groups here.

License

ltcache.go is released under the MIT License. Copyright (C) ITsysCOM GmbH. All Rights Reserved.

Sample usage code

package main

func main() {
	cache := NewCache(3, time.Duration(10*time.Millisecond), false, 
		func(k key, v interface{}) { fmt.Printf("Evicted key: %v, value: %v", k, v)})
	cache.Set("key1": "val1")
	cache.Get("key1")
	cache.Remove("key1")
	cache.Set(1, 1)
	cache.Remove(1)
	tc := NewTransCache(map[string]*CacheConfig{
		"dst_": &CacheConfig{MaxItems: -1},
		"rpf_": &CacheConfig{MaxItems: -1}})
	transID := tc.BeginTransaction()
	tc.Set("aaa_", "t31", "test", nil, false, transID)
	tc.Set("bbb_", "t32", "test", nil, false, transID)
	tc.CommitTransaction(transID)
	transID2 := tc.BeginTransaction()
	tc.Set("ccc_", "t31", "test", nil, false, transID2)
	tc.RollbackTransaction(transID2)
}

Documentation

Index

• Constants
• Variables
• func GenUUID() string
• type Cache
  • func NewCache(maxEntries int, ttl time.Duration, staticTTL bool, ...) (c *Cache)
  • func (c *Cache) Clear()
  • func (c *Cache) Get(itmID string) (value interface{}, ok bool)
  • func (c *Cache) GetCacheStats() (cs *CacheStats)
  • func (c *Cache) GetGroupItemIDs(grpID string) (itmIDs []string)
  • func (c *Cache) GetGroupItems(grpID string) (itms []interface{})
  • func (c *Cache) GetItemExpiryTime(itmID string) (exp time.Time, ok bool)
  • func (c *Cache) GetItemIDs(prfx string) (itmIDs []string)
  • func (c *Cache) GroupLength(grpID string) int
  • func (c *Cache) HasGroup(grpID string) (has bool)
  • func (c *Cache) HasItem(itmID string) (has bool)
  • func (c *Cache) Len() int
  • func (c *Cache) Remove(itmID string)
  • func (c *Cache) RemoveGroup(grpID string)
  • func (c *Cache) Set(itmID string, value interface{}, grpIDs []string)
• type CacheConfig
• type CacheStats
• type Cloner
• type TransCache
  • func NewTransCache(cfg map[string]*CacheConfig) (tc *TransCache)
  • func (tc *TransCache) BeginTransaction() (transID string)
  • func (tc *TransCache) Clear(chIDs []string)
  • func (tc *TransCache) CommitTransaction(transID string)
  • func (tc *TransCache) Get(chID, itmID string) (interface{}, bool)
  • func (tc *TransCache) GetCacheStats(chIDs []string) (cs map[string]*CacheStats)
  • func (tc *TransCache) GetCloned(chID, itmID string) (cln interface{}, err error)
  • func (tc *TransCache) GetGroupItemIDs(chID, grpID string) (itmIDs []string)
  • func (tc *TransCache) GetGroupItems(chID, grpID string) (itms []interface{})
  • func (tc *TransCache) GetItemExpiryTime(chID, itmID string) (exp time.Time, ok bool)
  • func (tc *TransCache) GetItemIDs(chID, prfx string) (itmIDs []string)
  • func (tc *TransCache) HasGroup(chID, grpID string) (has bool)
  • func (tc *TransCache) HasItem(chID, itmID string) (has bool)
  • func (tc *TransCache) Remove(chID, itmID string, commit bool, transID string)
  • func (tc *TransCache) RemoveGroup(chID, grpID string, commit bool, transID string)
  • func (tc *TransCache) RollbackTransaction(transID string)
  • func (tc *TransCache) Set(chID, itmID string, value interface{}, groupIDs []string, commit bool, ...)

Constants

const (
	UnlimitedCaching = -1
	DisabledCaching  = 0
)

const (
	AddItem              = "AddItem"
	RemoveItem           = "RemoveItem"
	RemoveGroup          = "RemoveGroup"
	DefaultCacheInstance = "*default"
)

Variables

var (
	ErrNotFound    = errors.New("not found")
	ErrNotClonable = errors.New("not clonable")
)

Functions

func GenUUID

func GenUUID() string

Types

type Cache

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

Cache is an LRU/TTL cache. It is safe for concurrent access.

func NewCache

func NewCache(maxEntries int, ttl time.Duration, staticTTL bool,
	onEvicted func(itmID string, value interface{})) (c *Cache)

New initializes a new cache.

func (*Cache) Clear

func (c *Cache) Clear()

Clear purges all stored items from the cache.

func (*Cache) Get

func (c *Cache) Get(itmID string) (value interface{}, ok bool)

Get looks up a key's value from the cache

func (*Cache) GetCacheStats

func (c *Cache) GetCacheStats() (cs *CacheStats)

GetStats will return the CacheStats for this instance

func (*Cache) GetGroupItemIDs

func (c *Cache) GetGroupItemIDs(grpID string) (itmIDs []string)

func (*Cache) GetGroupItems

func (c *Cache) GetGroupItems(grpID string) (itms []interface{})

func (*Cache) GetItemExpiryTime

func (c *Cache) GetItemExpiryTime(itmID string) (exp time.Time, ok bool)

func (*Cache) GetItemIDs

func (c *Cache) GetItemIDs(prfx string) (itmIDs []string)

GetItemIDs returns a list of items matching prefix

func (*Cache) GroupLength

func (c *Cache) GroupLength(grpID string) int

GroupLength returns the length of a group

func (*Cache) HasGroup

func (c *Cache) HasGroup(grpID string) (has bool)

func (*Cache) HasItem

func (c *Cache) HasItem(itmID string) (has bool)

func (*Cache) Len

func (c *Cache) Len() int

Len returns the number of items in the cache.

func (*Cache) Remove

func (c *Cache) Remove(itmID string)

Remove removes the provided key from the cache.

func (*Cache) RemoveGroup

func (c *Cache) RemoveGroup(grpID string)

func (*Cache) Set

func (c *Cache) Set(itmID string, value interface{}, grpIDs []string)

Set sets/adds a value to the cache.

type CacheConfig

type CacheConfig struct {
	MaxItems  int
	TTL       time.Duration
	StaticTTL bool
	OnEvicted func(itmID string, value interface{})
}

type CacheStats

type CacheStats struct {
	Items  int
	Groups int
}

type Cloner

type Cloner interface {
	Clone() (interface{}, error)
}

Cloner is an interface for objects to clone themselves into interface

type TransCache

type TransCache struct {
	// contains filtered or unexported fields
}

TransCache is a bigger cache with transactions and multiple Cache instances support

func NewTransCache

func NewTransCache(cfg map[string]*CacheConfig) (tc *TransCache)

NewTransCache instantiates a new TransCache

func (*TransCache) BeginTransaction

func (tc *TransCache) BeginTransaction() (transID string)

BeginTransaction initializes a new transaction into transactions buffer

func (*TransCache) Clear

func (tc *TransCache) Clear(chIDs []string)

Remove all items in one or more cache instances

func (*TransCache) CommitTransaction

func (tc *TransCache) CommitTransaction(transID string)

CommitTransaction executes the actions in a transaction buffer

func (*TransCache) Get

func (tc *TransCache) Get(chID, itmID string) (interface{}, bool)

Get returns the value of an Item

func (*TransCache) GetCacheStats

func (tc *TransCache) GetCacheStats(chIDs []string) (cs map[string]*CacheStats)

GetCacheStats returns on overview of full cache

func (*TransCache) GetCloned

func (tc *TransCache) GetCloned(chID, itmID string) (cln interface{}, err error)

GetCloned returns a clone of an Item if Item is clonable

func (*TransCache) GetGroupItemIDs

func (tc *TransCache) GetGroupItemIDs(chID, grpID string) (itmIDs []string)

GetGroupItems returns all items in a group. Nil if group does not exist

func (*TransCache) GetGroupItems

func (tc *TransCache) GetGroupItems(chID, grpID string) (itms []interface{})

GetGroupItems returns all items in a group. Nil if group does not exist

func (*TransCache) GetItemExpiryTime

func (tc *TransCache) GetItemExpiryTime(chID, itmID string) (exp time.Time, ok bool)

GetItemExpiryTime returns the expiry time of an item, ok is false if not found

func (*TransCache) GetItemIDs

func (tc *TransCache) GetItemIDs(chID, prfx string) (itmIDs []string)

GetItemIDs returns a list of item IDs matching prefix

func (*TransCache) HasGroup

func (tc *TransCache) HasGroup(chID, grpID string) (has bool)

func (*TransCache) HasItem

func (tc *TransCache) HasItem(chID, itmID string) (has bool)

HasItem verifies if Item is in the cache

func (*TransCache) Remove

func (tc *TransCache) Remove(chID, itmID string, commit bool, transID string)

RempveItem removes an item from the cache

func (*TransCache) RemoveGroup

func (tc *TransCache) RemoveGroup(chID, grpID string, commit bool, transID string)

RemoveGroup removes a group of items out of cache

func (*TransCache) RollbackTransaction

func (tc *TransCache) RollbackTransaction(transID string)

RollbackTransaction destroys a transaction from transactions buffer

func (*TransCache) Set

func (tc *TransCache) Set(chID, itmID string, value interface{},
	groupIDs []string, commit bool, transID string)

Set will add/edit an item to the cache