cache: github.com/koding/cache Index | Files

package cache

import "github.com/koding/cache"

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

Package Files

cache.go doc.go errors.go lfu.go lfu_nots.go lru.go lru_nots.go memory.go memory_nots.go memory_ttl.go mongo_cache.go mongo_model.go sharded_cache.go sharded_nots.go sharded_ttl.go

Variables

var (
    // ErrNotFound holds exported `not found error` for not found items
    ErrNotFound = errors.New("not found")
)

type Cache Uses

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 NewLFU Uses

func NewLFU(size int) Cache

NewLFU creates a thread-safe LFU cache

func NewLFUNoTS Uses

func NewLFUNoTS(size int) Cache

NewLFUNoTS creates a new LFU cache struct for further cache operations. Size is used for limiting the upper bound of the cache

func NewLRU Uses

func NewLRU(size int) Cache

NewLRU creates a thread-safe LRU cache

func NewLRUNoTS Uses

func NewLRUNoTS(size int) Cache

NewLRUNoTS creates a new LRU cache struct for further cache operations. Size is used for limiting the upper bound of the cache

func NewMemNoTSCache Uses

func NewMemNoTSCache() Cache

NewMemNoTSCache is a helper method to return a Cache interface, so callers don't have to typecast

func NewMemory Uses

func NewMemory() Cache

NewMemory creates an inmemory cache system Which everytime will return the true value about a cache hit

type Document Uses

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 Uses

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 Uses

func (l *LFU) Delete(key string) error

Delete deletes the given key-value pair from cache, this function doesnt return an error if item is not in the cache

func (*LFU) Get Uses

func (l *LFU) Get(key string) (interface{}, error)

Get returns the value of a given key if it exists, every get item will be increased for every usage

func (*LFU) Set Uses

func (l *LFU) Set(key string, val interface{}) error

Set sets or overrides the given key with the given value, every set item will be increased as usage. when the cache is full, least frequently used items will be evicted from linked list

type LFUNoTS Uses

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

LFUNoTS holds the cache struct

func (*LFUNoTS) Delete Uses

func (l *LFUNoTS) Delete(key string) error

Delete deletes the key and its dependencies

func (*LFUNoTS) Get Uses

func (l *LFUNoTS) Get(key string) (interface{}, error)

Get gets value of cache item then increments the usage of the item

func (*LFUNoTS) Set Uses

func (l *LFUNoTS) Set(key string, value interface{}) error

Set sets a new key-value pair Set increments the key usage count too

eg: cache.Set("test_key","2") cache.Set("test_key","1") if you try to set a value into same key its usage count will be increased and usage count of "test_key" will be 2 in this example

type LRU Uses

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 Uses

func (l *LRU) Delete(key string) error

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 Uses

func (l *LRU) Get(key string) (interface{}, error)

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

func (*LRU) Set Uses

func (l *LRU) Set(key string, val interface{}) error

Set sets or overrides the given key with the given value, every set item will be moved or prepended to the head of the linked list for keeping track of least recent used item. When the cache is full, last item of the linked list will be evicted from the cache

type LRUNoTS Uses

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 Uses

func (l *LRUNoTS) Delete(key string) error

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 Uses

func (l *LRUNoTS) Get(key string) (interface{}, error)

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

func (*LRUNoTS) Set Uses

func (l *LRUNoTS) Set(key string, val interface{}) error

Set sets or overrides the given key with the given value, every set item will be moved or prepended to the head of the linked list for keeping track of least recent used item. When the cache is full, last item of the linked list will be evicted from the cache

type Memory Uses

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 Uses

func (r *Memory) Delete(key string) error

Delete deletes the given key-value pair from cache, this function doesnt return an error if item is not in the cache

func (*Memory) Get Uses

func (r *Memory) Get(key string) (interface{}, error)

Get returns the value of a given key if it exists

func (*Memory) Set Uses

func (r *Memory) Set(key string, value interface{}) error

Set sets a value to the cache or overrides existing one with the given value

type MemoryNoTS Uses

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

MemoryNoTS provides a non-thread safe caching mechanism

func NewMemoryNoTS Uses

func NewMemoryNoTS() *MemoryNoTS

NewMemoryNoTS creates MemoryNoTS struct

func (*MemoryNoTS) Delete Uses

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 Uses

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 Uses

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 Uses

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 Uses

func NewMemoryWithTTL(ttl time.Duration) *MemoryTTL

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) Delete Uses

func (r *MemoryTTL) Delete(key string) error

Delete deletes a given key if exists

func (*MemoryTTL) Get Uses

func (r *MemoryTTL) Get(key string) (interface{}, error)

Get returns a value of a given key if it exists and valid for the time being

func (*MemoryTTL) Set Uses

func (r *MemoryTTL) Set(key string, value interface{}) error

Set will persist a value to the cache or override existing one with the new one

func (*MemoryTTL) StartGC Uses

func (r *MemoryTTL) StartGC(gcInterval time.Duration)

StartGC starts the garbage collection process in a go routine

func (*MemoryTTL) StopGC Uses

func (r *MemoryTTL) StopGC()

StopGC stops sweeping goroutine.

type MongoCache Uses

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 Uses

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 Uses

func (m *MongoCache) Delete(key string) error

Delete deletes a given key if exists

func (*MongoCache) EnsureIndex Uses

func (m *MongoCache) EnsureIndex() error

EnsureIndex ensures the index with expireAt key

func (*MongoCache) Get Uses

func (m *MongoCache) Get(key string) (interface{}, error)

Get returns a value of a given key if it exists

func (*MongoCache) Set Uses

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 Uses

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 Uses

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

func (*MongoCache) StopGC Uses

func (m *MongoCache) StopGC()

StopGC stops sweeping goroutine.

type Option Uses

type Option func(*MongoCache)

Option sets the options specified.

func MustEnsureIndexExpireAt Uses

func MustEnsureIndexExpireAt() Option

MustEnsureIndexExpireAt ensures the expireAt index usage: NewMongoCacheWithTTL(mongoSession, MustEnsureIndexExpireAt())

func SetCollectionName Uses

func SetCollectionName(collName string) Option

SetCollectionName sets the collection name for mongoDB in MongoCache struct as option usage: NewMongoCacheWithTTL(mongoSession, SetCollectionName("mongoCollName"))

func SetGCInterval Uses

func SetGCInterval(duration time.Duration) Option

SetGCInterval sets the garbage collector interval in MongoCache struct as option usage: NewMongoCacheWithTTL(mongoSession, SetGCInterval(time*Minute))

func SetTTL Uses

func SetTTL(duration time.Duration) Option

SetTTL sets the ttl duration in MongoCache as option usage: NewMongoCacheWithTTL(mongoSession, SetTTL(time*Minute))

func StartGC Uses

func StartGC() Option

StartGC enables the garbage collector in MongoCache struct usage: NewMongoCacheWithTTL(mongoSession, StartGC())

type ShardedCache Uses

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 Uses

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 Uses

func NewShardedNoTS(c func() Cache) *ShardedNoTS

NewShardedNoTS inits ShardedNoTS struct

func (*ShardedNoTS) Delete Uses

func (l *ShardedNoTS) Delete(tenantID, key string) error

Delete deletes a given key

func (*ShardedNoTS) DeleteShard Uses

func (l *ShardedNoTS) DeleteShard(tenantID string) error

DeleteShard deletes the keys inside from maps of cache & itemCount

func (*ShardedNoTS) Get Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

func (r *ShardedTTL) Delete(tenantID, key string) error

Delete deletes a given key if exists

func (*ShardedTTL) DeleteShard Uses

func (r *ShardedTTL) DeleteShard(tenantID string) error

DeleteShard deletes with given tenantID without key

func (*ShardedTTL) Get Uses

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 Uses

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 Uses

func (r *ShardedTTL) StartGC(gcInterval time.Duration)

StartGC starts the garbage collection process in a go routine

Package cache imports 7 packages (graph) and is imported by 81 packages. Updated 2016-12-23. Refresh now. Tools for package owners.