ltcache

package module
v0.0.0-...-a90b4db Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 9, 2025 License: MIT Imports: 18 Imported by: 7

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

View Source 
const (
	UnlimitedCaching = -1
	DisabledCaching  = 0
)
View Source 
const (
	AddItem              = "AddItem"
	RemoveItem           = "RemoveItem"
	RemoveGroup          = "RemoveGroup"
	DefaultCacheInstance = "*default"
)

Variables

View Source 
var (
	ErrNotFound    = errors.New("not found")
	ErrNotClonable = errors.New("not clonable")
)
View Source 
var ErrDumpIntervalDisabled = errors.New("dumpInterval is disabled")

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, clone bool,
	onEvicted []func(itmID string, value any)) (c *Cache)

NewCache initializes a new cache.

func NewCacheFromFolder 

func NewCacheFromFolder(offColl *OfflineCollector, maxEntries int, ttl time.Duration, staticTTL, clone bool, onEvicted []func(itmID string, value any)) (cache *Cache, err error)

NewCacheFromFolder construct a new Cache from reading dump files

func (*Cache) BackupCacheDumpFolder 

func (c *Cache) BackupCacheDumpFolder(backupFolderPath string, zip bool) (err error)

BackupCacheDumpFolder will backup the dump folder of the cache in backupFolderPath. zip true will compress the Cache dump folder and puts it in backupFolderPath (thread safe)

func (*Cache) Clear 

func (c *Cache) Clear()

Clear purges all stored items from the cache.

func (*Cache) DumpToFile 

func (c *Cache) DumpToFile() (err error)

DumpToFile dumps to file all of collected cache. (is thread safe)

func (*Cache) Get 

func (c *Cache) Get(itmID string) (value any, 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 []any)

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

func (c *Cache) RewriteDumpFiles() error

RewriteDumpFiles rewrites dump files of specified c Cache

func (*Cache) Set 

func (c *Cache) Set(itmID string, value any, grpIDs []string)

Set sets/adds a value to the cache.

func (*Cache) Shutdown 

func (c *Cache) Shutdown() (err error)

Shutdown depending on dump and rewrite intervals, will dump all thats left in cache collector to file and/or rewrite files, and close dump file

type CacheCloner 

type CacheCloner interface {
	CacheClone() any
}

CacheCloner is an interface for objects to clone themselves into interface

type CacheConfig 

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

type CacheStats 

type CacheStats struct {
	Items  int
	Groups int
}

type CollectionEntity 

type CollectionEntity struct {
	IsSet  bool   // Controls if the item that is collected is a SET or a REMOVE of the item from cache
	ItemID string // Holds the cache ItemID
}

CollectionEntity is used to temporarily collect cache keys of the items to be dumped to file

type OfflineCacheEntity 

type OfflineCacheEntity struct {
	IsSet      bool      // Controls if the item that is written is a SET or a REMOVE of the item
	ItemID     string    // Holds the cache ItemID to be stored in file
	Value      any       // Value of cache item to be stored in file
	GroupIDs   []string  // GroupIDs of cache item to be stored in file
	ExpiryTime time.Time // ExpiryTime of cache item to be stored in file
}

OfflineCacheEntity is used as the structure to be encoded/decoded per cache item to be dumped to file

type OfflineCollector 

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

OfflineCollector used dump cache to files

func NewOfflineCollector 

func NewOfflineCollector(cacheName string, opts *TransCacheOpts, logger logger) *OfflineCollector

NewOfflineCollector construct a new OfflineCollector

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 NewTransCacheWithOfflineCollector 

func NewTransCacheWithOfflineCollector(opts *TransCacheOpts, cfg map[string]*CacheConfig, l logger) (tc *TransCache, err error)

NewTransCacheWithOfflineCollector constructs a new TransCache with OfflineCollector if opts are provided. If not it runs NewTransCache constructor. Cache configuration is taken from cfg and logs will be sent to l logger.

func (*TransCache) BackupDumpFolder 

func (tc *TransCache) BackupDumpFolder(backupFolderPath string, zip bool) (err error)

BackupDumpFolder will momentarely stop any dumping and rewriting per Cache until their dump folder is backed up in folder path backupFolderPath, making zip true will create a zip file for each Cache dump in the backupFolderPath instead.

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

func (tc *TransCache) DumpAll() (err error)

DumpAll collected cache in files

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

func (tc *TransCache) RewriteAll() (err error)

RewriteAll will gather all sets and removes from dump files and rewrite a new streamlined file

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

func (*TransCache) Shutdown 

func (tc *TransCache) Shutdown()

Shutdown depending on dump and rewrite intervals, will dump all thats left in cache collector to file and/or rewrite files, and close all files

type TransCacheOpts 

type TransCacheOpts struct {
	DumpPath        string        // path where TransCache will be dumped
	BackupPath      string        // path where dump files will backup
	StartTimeout    time.Duration // if time to start TransCache passes this duration, it will stop and return error
	DumpInterval    time.Duration // dump frequency interval at which cache will be dumped to file (-1 dumps cache as soon as a set/remove is done; 0 disables it)
	RewriteInterval time.Duration // rewrite the dump files to streamline them, using RewriteInterval. (-2 rewrites on shutdown, -1 rewrites before start of dumping, 0 disables it).
	FileSizeLimit   int64         // File size limit in bytes. When limit is passed, it creates a new file where cache will be dumped. (only bigger than 0 allowed)
}

TransCacheOpts holds the options needed to create a TransCache with OfflineCollector

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.