From 238c0209c0faa5ccb8921aef3e448df6d7100939 Mon Sep 17 00:00:00 2001 From: Patrick Mylund Nielsen Date: Mon, 22 Dec 2014 01:55:57 -0500 Subject: [PATCH] New markdown README (thanks Jason Mooberry) --- README | 94 ------------------------------------------------ README.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 105 insertions(+), 94 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index 850d656..0000000 --- a/README +++ /dev/null @@ -1,94 +0,0 @@ -go-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. - -Although go-cache isn't meant to be used as a persistent datastore, the entire -cache may be saved to and loaded from a file (or any io.Reader/Writer) to -recover from downtime quickly. - -== Installation - -go get github.com/pmylund/go-cache - -== Usage - -import "github.com/pmylund/go-cache" - -// Create a cache with a default expiration time of 5 minutes, and which -// purges expired items every 30 seconds -c := cache.New(5*time.Minute, 30*time.Second) - -// Set the value of the key "foo" to "bar", with the default expiration time -c.Set("foo", "bar", 0) - -// Set the value of the key "baz" to 42, with no expiration time -// (the item won't be removed until it is re-set, or removed using -// c.Delete("baz") -c.Set("baz", 42, -1) - -// 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, 0) -if x, found := c.Get("foo"); found { - foo := x.(*MyStruct) - ... -} - -// If you store a reference type like a pointer, slice, map or channel, you -// do not need to run Set if you modify the underlying data. The cached -// reference points to the same memory, so if you modify a struct whose -// pointer you've stored in the cache, retrieving that pointer with Get will -// point you to the same data: -foo := &MyStruct{Num: 1} -c.Set("foo", foo, 0) -... -x, _ := c.Get("foo") -foo := x.(*MyStruct) -fmt.Println(foo.Num) -... -foo.Num++ -... -x, _ := c.Get("foo") -foo := x.(*MyStruct) -foo.Println(foo.Num) - -// will print: -1 -2 - -== Reference - -`go doc` or http://godoc.org/github.com/pmylund/go-cache diff --git a/README.md b/README.md new file mode 100644 index 0000000..129018f --- /dev/null +++ b/README.md @@ -0,0 +1,105 @@ +# go-cache + +go-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. + +Although go-cache isn't meant to be used as a persistent datastore, the entire +cache can be saved to and loaded from a file (using `c.Items()` to retrieve the +items map to serialize, and `NewFrom()` to create a cache from a deserialized +one) to recover from downtime quickly. (See the docs for `NewFrom` for caveats.) + +### Installation + +`go get github.com/pmylund/go-cache` + +### Usage + + import ( + "fmt" + "github.com/pmylund/go-cache" + ) + + func main() { + + // Create a cache with a default expiration time of 5 minutes, and which + // purges expired items every 30 seconds + c := cache.New(5*time.Minute, 30*time.Second) + + // Set the value of the key "foo" to "bar", with the default expiration time + c.Set("foo", "bar", cache.DefaultExpiration) + + // Set the value of the key "baz" to 42, with no expiration time + // (the item won't be removed until it is re-set, or removed using + // c.Delete("baz") + c.Set("baz", 42, cache.NoExpiration) + + // 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, cache.DefaultExpiration) + if x, found := c.Get("foo"); found { + foo := x.(*MyStruct) + // ... + } + + // If you store a reference type like a pointer, slice, map or channel, you + // do not need to run Set if you modify the underlying data. The cached + // reference points to the same memory, so if you modify a struct whose + // pointer you've stored in the cache, retrieving that pointer with Get will + // point you to the same data: + foo := &MyStruct{Num: 1} + c.Set("foo", foo, cache.DefaultExpiration) + // ... + x, _ := c.Get("foo") + foo := x.(*MyStruct) + fmt.Println(foo.Num) + // ... + foo.Num++ + // ... + x, _ := c.Get("foo") + foo := x.(*MyStruct) + foo.Println(foo.Num) + + // will print: + // 1 + // 2 + + } + + +### Reference + +`godoc` or [http://godoc.org/github.com/pmylund/go-cache](http://godoc.org/github.com/pmylund/go-cache)