README
¶
Cache 
Cache is a backend provider for common use cases
Install and Usage
Install the package with:
go get github.com/koding/cache
Import it with:
import "github.com/koding/cache"
Example
// create a cache with 2 second TTL
cache := NewMemoryWithTTL(2 * time.Second)
// start garbage collection for expired keys
cache.StartGC(time.Millisecond * 10)
// set item
err := cache.Set("test_key", "test_data")
// get item
data, err := cache.Get("test_key")
Supported caching algorithms:
- MemoryNoTS : provides a non-thread safe in-memory caching system
- Memory : provides a thread safe in-memory caching system, built on top of MemoryNoTS cache
- LRUNoTS : provides a non-thread safe, fixed size in-memory caching system, built on top of MemoryNoTS cache
- LRU : provides a thread safe, fixed size in-memory caching system, built on top of LRUNoTS cache
- MemoryTTL : provides a thread safe, expiring in-memory caching system, built on top of MemoryNoTS cache
- ShardedNoTS : provides a non-thread safe sharded cache system, built on top of a cache interface
- ShardedTTL : provides a thread safe, expiring in-memory sharded cache system, built on top of ShardedNoTS over MemoryNoTS
- LFUNoTS : provides a non-thread safe, fixed size in-memory caching system, built on top of MemoryNoTS cache
- LFU : provides a thread safe, fixed size in-memory caching system, built on top of LFUNoTS cache
Documentation
¶
Overview ¶
Package cache provides basic caching mechanisms for Go(lang) projects.
Currently supported caching algorithms:
MemoryNoTS : provides a non-thread safe in-memory caching system Memory : provides a thread safe in-memory caching system, built on top of MemoryNoTS cache LRUNoTS : provides a non-thread safe, fixed size in-memory caching system, built on top of MemoryNoTS cache LRU : provides a thread safe, fixed size in-memory caching system, built on top of LRUNoTS cache MemoryTTL : provides a thread safe, expiring in-memory caching system, built on top of MemoryNoTS cache ShardedNoTS : provides a non-thread safe sharded cache system, built on top of a cache interface ShardedTTL : provides a thread safe, expiring in-memory sharded cache system, built on top of ShardedNoTS over MemoryNoTS LFUNoTS : provides a non-thread safe, fixed size in-memory caching system, built on top of MemoryNoTS cache LFU : provides a thread safe, fixed size in-memory caching system, built on top of LFUNoTS cache
Index ¶
- Variables
- type Cache
- type Document
- type LFU
- type LFUNoTS
- type LRU
- type LRUNoTS
- type Memory
- type MemoryNoTS
- type MemoryTTL
- type MongoCache
- func (m *MongoCache) Delete(key string) error
- func (m *MongoCache) EnsureIndex() error
- func (m *MongoCache) Get(key string) (interface{}, error)
- func (m *MongoCache) Set(key string, value interface{}) error
- func (m *MongoCache) SetEx(key string, duration time.Duration, value interface{}) error
- func (m *MongoCache) StartGC(gcInterval time.Duration)
- func (m *MongoCache) StopGC()
- type Option
- type ShardedCache
- type ShardedNoTS
- type ShardedTTL
- func (r *ShardedTTL) Delete(tenantID, key string) error
- func (r *ShardedTTL) DeleteShard(tenantID string) error
- func (r *ShardedTTL) Get(tenantID, key string) (interface{}, error)
- func (r *ShardedTTL) Set(tenantID, key string, value interface{}) error
- func (r *ShardedTTL) StartGC(gcInterval time.Duration)
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNotFound holds exported `not found error` for not found items ErrNotFound = errors.New("not found") )
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache interface {
// Get returns single item from the backend if the requested item is not
// found, returns NotFound err
Get(key string) (interface{}, error)
// Set sets a single item to the backend
Set(key string, value interface{}) error
// Delete deletes single item from backend
Delete(key string) error
}
Cache is the contract for all of the cache backends that are supported by this package
func NewLFUNoTS ¶
NewLFUNoTS creates a new LFU cache struct for further cache operations. Size is used for limiting the upper bound of the cache
func NewLRUNoTS ¶
NewLRUNoTS creates a new LRU cache struct for further cache operations. Size is used for limiting the upper bound of the cache
func NewMemNoTSCache ¶
func NewMemNoTSCache() Cache
NewMemNoTSCache is a helper method to return a Cache interface, so callers don't have to typecast
type Document ¶
type Document struct {
Key string `bson:"_id" json:"_id"`
Value interface{} `bson:"value" json:"value"`
ExpireAt time.Time `bson:"expireAt" json:"expireAt"`
}
Document holds the key-value pair for mongo cache
type LFU ¶
type LFU struct {
// Mutex is used for handling the concurrent
// read/write requests for cache
sync.Mutex
// contains filtered or unexported fields
}
LFU holds the Least frequently used cache values
func (*LFU) Delete ¶
Delete deletes the given key-value pair from cache, this function doesnt return an error if item is not in the cache
type LFUNoTS ¶
type LFUNoTS struct {
// contains filtered or unexported fields
}
LFUNoTS holds the cache struct
type LRU ¶
type LRU struct {
// Mutex is used for handling the concurrent
// read/write requests for cache
sync.Mutex
// contains filtered or unexported fields
}
LRU Discards the least recently used items first. This algorithm requires keeping track of what was used when.
func (*LRU) Delete ¶
Delete deletes the given key-value pair from cache, this function doesnt return an error if item is not in the cache
func (*LRU) Get ¶
Get returns the value of a given key if it exists, every get item will be moved to the head of the linked list for keeping track of least recent used item
type LRUNoTS ¶
type LRUNoTS struct {
// contains filtered or unexported fields
}
LRUNoTS Discards the least recently used items first. This algorithm requires keeping track of what was used when.
func (*LRUNoTS) Delete ¶
Delete deletes the given key-value pair from cache, this function doesnt return an error if item is not in the cache
func (*LRUNoTS) Get ¶
Get returns the value of a given key if it exists, every get item will be moved to the head of the linked list for keeping track of least recent used item
type Memory ¶
type Memory struct {
// Mutex is used for handling the concurrent
// read/write requests for cache
sync.Mutex
// contains filtered or unexported fields
}
Memory provides an inmemory caching mechanism
func (*Memory) Delete ¶
Delete deletes the given key-value pair from cache, this function doesnt return an error if item is not in the cache
type MemoryNoTS ¶
type MemoryNoTS struct {
// contains filtered or unexported fields
}
MemoryNoTS provides a non-thread safe caching mechanism
func (*MemoryNoTS) Delete ¶
func (r *MemoryNoTS) Delete(key string) error
Delete deletes a given key, it doesnt return error if the item is not in the system
func (*MemoryNoTS) Get ¶
func (r *MemoryNoTS) Get(key string) (interface{}, error)
Get returns a value of a given key if it exists and valid for the time being
func (*MemoryNoTS) Set ¶
func (r *MemoryNoTS) Set(key string, value interface{}) error
Set will persist a value to the cache or override existing one with the new one
type MemoryTTL ¶
type MemoryTTL struct {
// Mutex is used for handling the concurrent
// read/write requests for cache
sync.RWMutex
// contains filtered or unexported fields
}
MemoryTTL holds the required variables to compose an in memory cache system which also provides expiring key mechanism
func NewMemoryWithTTL ¶
NewMemoryWithTTL creates an inmemory cache system Which everytime will return the true values about a cache hit and never will leak memory ttl is used for expiration of a key from cache
func (*MemoryTTL) Get ¶
Get returns a value of a given key if it exists and valid for the time being
func (*MemoryTTL) Set ¶
Set will persist a value to the cache or override existing one with the new one
type MongoCache ¶
type MongoCache struct {
// CollectionName speficies the optional collection name for mongoDB
// if CollectionName is not set, then default value will be set
CollectionName string
// ttl is a duration for a cache key to expire
TTL time.Duration
// GCInterval specifies the time duration for garbage collector time interval
GCInterval time.Duration
// GCStart starts the garbage collector and deletes the
// expired keys from mongo with given time interval
GCStart bool
// Mutex is used for handling the concurrent
// read/write requests for cache
sync.RWMutex
// contains filtered or unexported fields
}
MongoCache holds the cache values that will be stored in mongoDB
func NewMongoCacheWithTTL ¶
func NewMongoCacheWithTTL(session *mgo.Session, configs ...Option) *MongoCache
NewMongoCacheWithTTL creates a caching layer backed by mongo. TTL's are managed either by a background cleaner or document is removed on the Get operation. Mongo TTL indexes are not utilized since there can be multiple systems using the same collection with different TTL values.
The responsibility of stopping the GC process belongs to the user.
Session is not closed while stopping the GC.
This self-referential function satisfy you to avoid passing nil value to the function as parameter e.g (usage) : configure with defaults, just call; NewMongoCacheWithTTL(session)
configure ttl duration with;
NewMongoCacheWithTTL(session, func(m *MongoCache) {
m.TTL = 2 * time.Minute
})
or NewMongoCacheWithTTL(session, SetTTL(time.Minute * 2))
configure collection name with;
NewMongoCacheWithTTL(session, func(m *MongoCache) {
m.CollectionName = "MongoCacheCollectionName"
})
func (*MongoCache) Delete ¶
func (m *MongoCache) Delete(key string) error
Delete deletes a given key if exists
func (*MongoCache) EnsureIndex ¶
func (m *MongoCache) EnsureIndex() error
EnsureIndex ensures the index with expireAt key
func (*MongoCache) Get ¶
func (m *MongoCache) Get(key string) (interface{}, error)
Get returns a value of a given key if it exists
func (*MongoCache) Set ¶
func (m *MongoCache) Set(key string, value interface{}) error
Set will persist a value to the cache or override existing one with the new one
func (*MongoCache) SetEx ¶
func (m *MongoCache) SetEx(key string, duration time.Duration, value interface{}) error
SetEx will persist a value to the cache or override existing one with the new one with ttl duration
func (*MongoCache) StartGC ¶
func (m *MongoCache) StartGC(gcInterval time.Duration)
StartGC starts the garbage collector with given time interval The expired data will be checked & deleted with given interval time
type Option ¶
type Option func(*MongoCache)
Option sets the options specified.
func MustEnsureIndexExpireAt ¶
func MustEnsureIndexExpireAt() Option
MustEnsureIndexExpireAt ensures the expireAt index usage: NewMongoCacheWithTTL(mongoSession, MustEnsureIndexExpireAt())
func SetCollectionName ¶
SetCollectionName sets the collection name for mongoDB in MongoCache struct as option usage: NewMongoCacheWithTTL(mongoSession, SetCollectionName("mongoCollName"))
func SetGCInterval ¶
SetGCInterval sets the garbage collector interval in MongoCache struct as option usage: NewMongoCacheWithTTL(mongoSession, SetGCInterval(time*Minute))
type ShardedCache ¶
type ShardedCache interface {
// Get returns single item from the backend if the requested item is not
// found, returns NotFound err
Get(shardID, key string) (interface{}, error)
// Set sets a single item to the backend
Set(shardID, key string, value interface{}) error
// Delete deletes single item from backend
Delete(shardID, key string) error
// Deletes all items in that shard
DeleteShard(shardID string) error
}
ShardedCache is the contract for all of the sharded cache backends that are supported by this package
type ShardedNoTS ¶
type ShardedNoTS struct {
// contains filtered or unexported fields
}
ShardedNoTS ; the concept behind this storage is that each cache entry is associated with a tenantID and this enables fast purging for just that tenantID
func NewShardedNoTS ¶
func NewShardedNoTS(c func() Cache) *ShardedNoTS
NewShardedNoTS inits ShardedNoTS struct
func (*ShardedNoTS) Delete ¶
func (l *ShardedNoTS) Delete(tenantID, key string) error
Delete deletes a given key
func (*ShardedNoTS) DeleteShard ¶
func (l *ShardedNoTS) DeleteShard(tenantID string) error
DeleteShard deletes the keys inside from maps of cache & itemCount
func (*ShardedNoTS) Get ¶
func (l *ShardedNoTS) Get(tenantID, key string) (interface{}, error)
Get returns a value of a given key if it exists and valid for the time being
func (*ShardedNoTS) Set ¶
func (l *ShardedNoTS) Set(tenantID, key string, val interface{}) error
Set will persist a value to the cache or override existing one with the new one
type ShardedTTL ¶
type ShardedTTL struct {
// Mutex is used for handling the concurrent
// read/write requests for cache
sync.Mutex
// contains filtered or unexported fields
}
ShardedTTL holds the required variables to compose an in memory sharded cache system which also provides expiring key mechanism
func NewShardedCacheWithTTL ¶
func NewShardedCacheWithTTL(ttl time.Duration, f func() Cache) *ShardedTTL
NewShardedCacheWithTTL creates a sharded cache system with TTL based on specified Cache constructor Which everytime will return the true values about a cache hit and never will leak memory ttl is used for expiration of a key from cache
func NewShardedWithTTL ¶
func NewShardedWithTTL(ttl time.Duration) *ShardedTTL
NewShardedWithTTL creates an in-memory sharded cache system ttl is used for expiration of a key from cache
func (*ShardedTTL) Delete ¶
func (r *ShardedTTL) Delete(tenantID, key string) error
Delete deletes a given key if exists
func (*ShardedTTL) DeleteShard ¶
func (r *ShardedTTL) DeleteShard(tenantID string) error
DeleteShard deletes with given tenantID without key
func (*ShardedTTL) Get ¶
func (r *ShardedTTL) Get(tenantID, key string) (interface{}, error)
Get returns a value of a given key if it exists and valid for the time being
func (*ShardedTTL) Set ¶
func (r *ShardedTTL) Set(tenantID, key string, value interface{}) error
Set will persist a value to the cache or override existing one with the new one
func (*ShardedTTL) StartGC ¶
func (r *ShardedTTL) StartGC(gcInterval time.Duration)
StartGC starts the garbage collection process in a go routine
Source Files