Origin check in

Author: John Farley

README.md

@@ -0,0 +1,91 @@
+# go-simple-cache
+
+go-simple-cache is an in-memory key:value store/cache similar to memcached that is suitable for applications running on a single machine. Its major advantage is that, being essentially a thread-safe map[string]interface{} with expiration times, it doesn't need to serialize or transmit its contents over the network.
+
+Any object can be stored, for a given duration or forever, and the cache can be safely used by multiple goroutines.
+
+Source code originally forked from: 
+https://github.com/patrickmn/go-cache
+
+This forked version of go-cache is a simplified version of the original. This version 
+has the following changes from the original:
+
+1. expired items stay in the cache, but a user provided callback function is executed when the cache expires
+2. cache expiration is applied to the entire cache, rather than to individual keys
+3. removed increment/decrement feature
+4. removed ability to persist cache to disk
+5. removed auto eviction of expired items
+
+### Use Case
+
+This version of the library is ideal as a simple lookup cache that is populated by a relatively static list 
+of items that have a limited life or that change infrequently. For example, you fetch a list of records from 
+a lookup table in a database and put them in the cache with a timeout of 24hrs. The data in the database changes 
+infrequently, which justifies the 24hr timeout, and performing the lookup from the cache is faster than going 
+back to the database. When the 24hr timeout is reached, a callback function is executed and the cache is refreshed 
+with the latest data from the database. 
+
+### Installation
+
+`go get github.com/jfarleyx/go-simple-cache`
+
+### Usage
+
+```go
+import (
+	"fmt"
+	"github.com/jfarleyx/go-simple-cache"
+	"time"
+)
+
+func main() {
+	// Create a cache with a default expiration time of 5 hours
+	c := cache.New(5*time.Hour)
+
+	// Provide a callback function that is called when the cache expires
+	myfunc := func() {
+		// e.g. fetch current data and refill cache
+	}
+	c.cache.OnExpired(myfunc)
+
+	// Set the value of the key "foo" to "bar"
+	c.Set("foo", "bar")
+
+	// Get the string associated with the key "foo" from the cache
+	foo, found := c.Get("foo")
+	if found {
+		fmt.Println(foo)
+	}
+
+	// Since Go is statically typed, and cache values can be anything, type
+	// assertion is needed when values are being passed to functions that don't
+	// take arbitrary types, (i.e. interface{}). The simplest way to do this for
+	// values which will only be used once--e.g. for passing to another
+	// function--is:
+	foo, found := c.Get("foo")
+	if found {
+		MyFunction(foo.(string))
+	}
+
+	// This gets tedious if the value is used several times in the same function.
+	// You might do either of the following instead:
+	if x, found := c.Get("foo"); found {
+		foo := x.(string)
+		// ...
+	}
+	// or
+	var foo string
+	if x, found := c.Get("foo"); found {
+		foo = x.(string)
+	}
+	// ...
+	// foo can then be passed around freely as a string
+
+	// Want performance? Store pointers!
+	c.Set("foo", &MyStruct)
+	if x, found := c.Get("foo"); found {
+		foo := x.(*MyStruct)
+			// ...
+	}
+}
+```

cache.go

@@ -0,0 +1,210 @@
+package cache
+
+import (
+	"fmt"
+	"runtime"
+	"sync"
+	"time"
+)
+
+// Item represents an item in the cache.
+type Item struct {
+	Object     interface{}
+	Expiration int64
+}
+
+// Expired returns true if the item has expired.
+func (item Item) Expired() bool {
+	if item.Expiration == 0 {
+		return false
+	}
+	return time.Now().UnixNano() > item.Expiration
+}
+
+// Cache is the cache object
+type Cache struct {
+	*cache
+	// If this is confusing, see the comment at the bottom of New()
+}
+
+type cache struct {
+	expiration time.Duration
+	items      map[string]Item
+	mu         sync.RWMutex
+	onExpired  func()
+	janitor    *janitor
+}
+
+// Set add an item to the cache, replacing any existing item.
+func (c *cache) Set(k string, x interface{}) {
+	// "Inlining" of set
+	var e = time.Now().Add(c.expiration).UnixNano()
+
+	c.mu.Lock()
+	c.items[k] = Item{
+		Object:     x,
+		Expiration: e,
+	}
+	// TODO: Calls to mu.Unlock are currently not deferred because defer
+	// adds ~200 ns (as of go1.)
+	c.mu.Unlock()
+}
+
+func (c *cache) set(k string, x interface{}) {
+	var e = time.Now().Add(c.expiration).UnixNano()
+	c.items[k] = Item{
+		Object:     x,
+		Expiration: e,
+	}
+}
+
+// Replace set a new value for the cache key only if it already exists. Returns an error otherwise.
+func (c *cache) Replace(k string, x interface{}) error {
+	c.mu.Lock()
+	_, found := c.get(k)
+	if !found {
+		c.mu.Unlock()
+		return fmt.Errorf("Item %s doesn't exist", k)
+	}
+	c.set(k, x)
+	c.mu.Unlock()
+	return nil
+}
+
+// Get an item from the cache. Returns the item or nil, and a bool indicating
+// whether the key was found.
+func (c *cache) Get(k string) (interface{}, bool) {
+	c.mu.RLock()
+	item, found := c.items[k]
+	if !found {
+		c.mu.RUnlock()
+		return nil, false
+	}
+	c.mu.RUnlock()
+	return item.Object, true
+}
+
+func (c *cache) get(k string) (interface{}, bool) {
+	item, found := c.items[k]
+	if !found {
+		return nil, false
+	}
+	return item.Object, true
+}
+
+// Delete an item from the cache. Does nothing if the key is not in the cache.
+func (c *cache) Delete(k string) {
+	c.mu.Lock()
+	delete(c.items, k)
+	c.mu.Unlock()
+}
+
+// Delete all expired items from the cache.
+func (c *cache) DeleteExpired() {
+	now := time.Now().UnixNano()
+	c.mu.Lock()
+	for k, v := range c.items {
+		if v.Expiration > 0 && now > v.Expiration {
+			delete(c.items, k)
+		}
+	}
+	c.mu.Unlock()
+}
+
+type keyAndValue struct {
+	key   string
+	value interface{}
+}
+
+// OnExpired sets an (optional) function that is called when the cache expires
+func (c *cache) OnExpired(f func()) {
+	c.onExpired = f
+}
+
+// Returns the number of items in the cache, including expired items.
+func (c *cache) ItemCount() int {
+	c.mu.RLock()
+	n := len(c.items)
+	c.mu.RUnlock()
+	return n
+}
+
+// Delete all items from the cache.
+func (c *cache) Flush() {
+	c.mu.Lock()
+	c.items = map[string]Item{}
+	c.mu.Unlock()
+}
+
+type janitor struct {
+	Interval time.Duration
+	stop     chan bool
+}
+
+// handleExpired is fired by the ticker and executes the onExpired function.
+func (c *cache) handleExpired() {
+	if c.onExpired != nil {
+		c.onExpired()
+	}
+}
+
+func (j *janitor) Run(c *cache) {
+	ticker := time.NewTicker(j.Interval)
+	for {
+		select {
+		case <-ticker.C:
+			c.handleExpired()
+		case <-j.stop:
+			ticker.Stop()
+			return
+		}
+	}
+}
+
+func stopJanitor(c *Cache) {
+	c.janitor.stop <- true
+}
+
+func runJanitor(c *cache, ex time.Duration) {
+	j := &janitor{
+		Interval: ex,
+		stop:     make(chan bool, 1),
+	}
+	c.janitor = j
+	go j.Run(c)
+}
+
+func newCache(ex time.Duration, m map[string]Item) *cache {
+	if ex <= 0 {
+		ex = -1
+	}
+	c := &cache{
+		expiration: ex,
+		items:      m,
+	}
+	return c
+}
+
+func newCacheWithJanitor(ex time.Duration, m map[string]Item) *Cache {
+	c := newCache(ex, m)
+	// This trick ensures that the janitor goroutine (which--granted it
+	// was enabled--is running DeleteExpired on c forever) does not keep
+	// the returned C object from being garbage collected. When it is
+	// garbage collected, the finalizer stops the janitor goroutine, after
+	// which c can be collected.
+	C := &Cache{c}
+	if ex > 0 {
+		runJanitor(c, ex)
+		runtime.SetFinalizer(C, stopJanitor)
+	}
+	return C
+}
+
+// New return a new cache with a given expiration duration. If the
+// expiration duration is less than 1 (i.e. No Expiration),
+// the items in the cache never expire (by default), and must be deleted
+// manually. The OnExpired callback method is ignored, too.
+func New(expiration time.Duration) *Cache {
+	items := make(map[string]Item)
+	return newCacheWithJanitor(expiration, items)
+}