spectre

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

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

 Go to latest Published: Dec 16, 2016 License: Apache-2.0 Imports: 8 Imported by: 0

README

# spectre Dont fear ... its a friendly ghost . Spectre is a goroutine safe process level cache following LRU pattern with ttl (time to live) for each key. When the memory gets fully utilised , the key which has been used before a long time is evicted . Also there is a cleanup methods for expired keys at the time of SET and DELETE actions . This cleanup ensure to keep the memory free from expired keys for other process. In web servers there is lots of memory availble at cheaper cost which can be utilised in optimum manner to get the right benefit. Spectre caches the serialised data for a string key which can save a same next heavy cpu based computation or a network call.

##How to install:

go get github.com/vivek07672/spectre

##How to use:

...

import "github.com/vivek07672/spectre"

// so the first step is to get the cache variable
volatileLRUCache := volatileLRUCache.GetVolatileLRUCache(cacheSize int, cachePartitions int, ttl time.Duration)
the parameters :
	cacheSize: size of ram memory in bytes that is to be allocated to the cache
	cachePartitions: no of internal maps to be used
				- larger the number better thread safe (32 is a good count )
			 inside total this many maps are kept to cache the date , each map can give access to 
			 one goroutine at any time .
	ttl: a global timeout for all the keys
	
// now its time for some operation testing
// SETTING IN CACHE
	fmt.Print("Enter the key: \n")
	fmt.Scanf("%s", &key)
	fmt.Print("Enter the value: \n")
	fmt.Scanf("%s", &value)
	serialisedValue := []byte(value)
	size = int(binary.Size(serialisedValue))
	// here time.Duration(0) is setting the key level expire ; 0 is duration seconds after which key gets expired 
	volatileLRUCache.VolatileLRUCacheSet(key, serialisedValue, size, time.Duration(0))

Note : local exire has priority over global expiry . 

// GETTING FROM CACHE
	var key string
	fmt.Print("Enter the key: \n")
	fmt.Scanf("%s", &key)
	val, ok := volatileLRUCache.VolatileLRUCacheGet(key)
	fmt.Printf("value = %v and ok = %v\n", string(val), ok)
	fmt.Printf("type of value is = %T", val)

// DELETING FROM CACHE
	var key string
	fmt.Print("Enter the key: \n")
	fmt.Scanf("%s", &key)
	volatileLRUCache.VolatileLRUCacheDelete(key)
...

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// SizeLimitError returns when size of value is greater then total allocated memory
	SizeLimitError = &sizeLimitError{problem: "data size is more than max size", errorNumber: 0}
	// LowSpaceError returns when size of the value is greater than current available space
	LowSpaceError = &lowSpaceError{problem: "space not available", errorNumber: 1}
)
View Source 
var SHARD_COUNT int

SHARD_COUNT is the number of golang maps that are going to participate in caching internally.

Functions

This section is empty.

Types

type Cache 

type Cache struct {
	MaxSize      int
	CurrentSize  int
	Size         map[string]int
	Data         *cacheData
	sync.RWMutex // for atomic CurrentSize modification
}

Cache is the stucture resposible to handle the cache key and value. This structure having the following parameters in it : 

MaxSize: maximum size of the cache object
CurrentSize: current size of the cache object
Size: a golang map to store the values size key wise.
	  this structure save the cpu cyclone to calculate he size
	  many time
Data: a pointer to the cacheData in which threadsafe maps are
	  storing the values
sync.RWMutex: to ensure the thread safety for this structure

func GetDefaultCache 

func GetDefaultCache(cacheSize int, cachePartitions int) *Cache

GetDefaultCache returns the most abstract cache just using the cap in memory limit . Cache is having algorithm to evict key when space is not available in random selection.

func (*Cache) CacheDelete 

func (c *Cache) CacheDelete(key string)

CacheDelete deletes the key in the cache.

func (*Cache) CacheGet 

func (c *Cache) CacheGet(key string) (interface{}, bool)

CacheGet returns the value in the cache pointed by the input key parameter. return values : 

ok: true if success else false
val: value corresponding to the key

func (*Cache) CacheGetAllKeys 

func (c *Cache) CacheGetAllKeys() []string

func (*Cache) CacheIterator 

func (c *Cache) CacheIterator(outputChannel chan CacheRow)

CacheIterator returns all the key and value pair one by one in the input CacheRow channel. Calling goroutine returns immediately after spawning a gourtine. Spawned goroutine fills the channel with CacheRow. When there is not any CacheRow left, spawned goroutine closes the channel.

func (*Cache) CacheSet 

func (c *Cache) CacheSet(key string, value interface{}, size int) (bool, error)

CacheSet sets the key with its corresponding value in the cache. In case of memory unavailability, It frees some space with the defined algorithm and sets the key.size of the key is in bytes. return values : 

success: true if success else false
error: error in the operation

func (*Cache) ClearCache 

func (c *Cache) ClearCache()

ClearCache clears all the keys in the cache.

func (*Cache) GetCurrentSize 

func (c *Cache) GetCurrentSize() int

GetCurrentSize return the current size of the cache.

func (*Cache) SetData 

func (c *Cache) SetData(key string, value interface{}, size int) (bool, error)

SetData sets a key and its corresponding value in the cache. This methods is responsible to set in the cache when there is other algorithm is applied for key eviction in case of memory unavailability. returns : 

retFlag: true if space is available else false
error: if any error in the operation else nil

func (*Cache) String 

func (c *Cache) String() string

type CacheRow 

type CacheRow struct {
	Key   string
	Value interface{}
}

CacheRow is a entry in cache having structure like (key: value)

func (CacheRow) String 

func (c CacheRow) String() string
type Link struct {
	ExpireTime time.Time
	// contains filtered or unexported fields
}

Link is a node in circular doubly linked list that stores information about the key usage and time to live structure is like :

link1 prev\ /link2 next 

		link1		   link2
 link1 next\        	/link2 prev
			\		   /
			 \		  /
    root prev \      /root next
			    ROOT

type VolatileLRUCache 

type VolatileLRUCache struct {
	sync.RWMutex // to make double linked list thread safe
	// contains filtered or unexported fields
}

VolatileLRUCache is a cache wrapper on top of Cache. so still the maximum size of the cache is controlled by Cache only. This wrapper just adds an algorithm for key eviction policy . In case of memory unavailability VolatileLRUCache deletes the keys in the following order : 

*** keys which has been expired then the keys which are
*** keys which are least recently used

VolatileLRUCache maintains a circular doubly link list in memory to have the meta data of the keys ready. Also this structure is thread safe; meaning several goroutine can operate concurrently.

func GetVolatileLRUCache 

func GetVolatileLRUCache(cacheSize int, cachePartitions int, ttl time.Duration) *VolatileLRUCache

GetVolatileLRUCache returns an instance of VolatileLRUCache with the specified input params: 

cacheSize: size of the cache in bytes
cachePartitions: total number map participating in internal cache.
ttl: a global time duration for each key expiration.

func (*VolatileLRUCache) GetLRUInfo 

func (vlruCache *VolatileLRUCache) GetLRUInfo() string

GetLRUInfo return the lru information of the keys in VolatileLRUCache.

func (*VolatileLRUCache) GetTTLInfo 

func (vlruCache *VolatileLRUCache) GetTTLInfo() string

GetLRUInfo return the ttl information of the keys in VolatileLRUCache.

func (*VolatileLRUCache) RemoveVolatileKey 

func (vlruCache *VolatileLRUCache) RemoveVolatileKey()

RemoveVolatileKey removes the keys which are already expired in VolatileLRUCache.

func (*VolatileLRUCache) String 

func (vlruCache *VolatileLRUCache) String() string

func (*VolatileLRUCache) VolatileLRUCacheClear 

func (vlruCache *VolatileLRUCache) VolatileLRUCacheClear()

VolatileLRUCacheClear clears all the keys in the cache.

func (*VolatileLRUCache) VolatileLRUCacheCurrentSize 

func (vlruCache *VolatileLRUCache) VolatileLRUCacheCurrentSize() int

GetCurrentSize is a wrapper on top of Cache GetCurrentSize which returns the current VolatileLRUCache size in bytes.

func (*VolatileLRUCache) VolatileLRUCacheDelete 

func (vlruCache *VolatileLRUCache) VolatileLRUCacheDelete(key string)

VolatileLRUCacheDelete deletes a key present in VolatileLRUCache.

func (*VolatileLRUCache) VolatileLRUCacheGet 

func (vlruCache *VolatileLRUCache) VolatileLRUCacheGet(key string) (interface{}, bool)

VolatileLRUCacheGet returns the value corresponding to a key present in Cache. This also modify internal doubly link list to maintain the updated ttl and lru info of the keys preset in Cache. return values : 

value: value corresponding to the key
ok: true if success else false

func (*VolatileLRUCache) VolatileLRUCacheIterator 

func (vlruCache *VolatileLRUCache) VolatileLRUCacheIterator(outputChannel chan CacheRow)

func (*VolatileLRUCache) VolatileLRUCacheSet 

func (vlruCache *VolatileLRUCache) VolatileLRUCacheSet(key string, value interface{}, size int, keyExpire time.Duration) (bool, error)

func (*VolatileLRUCache) VolatileLRUCachedKeys 

func (vlruCache *VolatileLRUCache) VolatileLRUCachedKeys() (keySet []string)

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.