diff --git a/README b/README new file mode 100644 index 0000000..5ee7182 --- /dev/null +++ b/README @@ -0,0 +1,76 @@ +go-cache is an in-memory key:value store/cache similar to memcached that is suitable for +applications running on a single machine. Any object can be stored, for a given duration +or forever, and the cache can be used safely by multiple goroutines. + +Installation: + goinstall github.com/pmylund/go-cache + +Usage: + // 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 "yes", with no expiration time (the item + // won't be removed until it is re-set, or removed using c.Delete("baz") + c.Set("baz", "yes", -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 cache does not serialize its data, 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 diff --git a/cache.go b/cache.go index 0473e40..10cafc6 100644 --- a/cache.go +++ b/cache.go @@ -8,7 +8,7 @@ import ( "time" ) -// Cache is an in-memory key:value store/cache similar to memcached that is suitable for +// go-cache is an in-memory key:value store/cache similar to memcached that is suitable for // applications running on a single machine. Any object can be stored, for a given duration // or forever, and the cache can be used safely by multiple goroutines. //