The go-cache library is a high-performance, in-memory key-value store written in Go, designed to provide fast, temporary storage for your applications. It is suitable for caching purposes where data needs to be accessed quickly and frequently, but persistence is not required.
Thank you for your support! ❤️
- Simple and Easy to Use: The library offers a straightforward interface for common cache operations like adding, retrieving, and deleting items.
- Flexible Expiration: Items can have custom expiration times, including no expiration. This is useful for controlling the lifespan of cached data.
- Automatic Expiration: Automatically removes expired items based on a configurable cleanup interval, ensuring efficient memory usage.
- Thread-Safe: The library uses synchronization primitives to ensure safe concurrent access to the cache.
- Support for Various Types: It supports caching items of various types including int, float32, float64, and more.
- Serialization: Provides methods to save and load cache data using Gob encoding.
The go-cache library is structured to offer both a standard cache and a sharded cache for higher concurrency needs.
- Cache: The main cache structure that stores items and handles operations like set, get, delete, etc.
- Item: Represents an individual cached item with its value and expiration time.
- Janitor: A background process that periodically cleans up expired items from the cache.
For scenarios requiring high concurrency, the library provides a sharded cache implementation:
- shardedCache: Splits the cache into multiple shards, each managed by its own Cache instance to reduce lock contention.
- shardedJanitor: A janitor process specific to the sharded cache, responsible for cleaning up expired items in each shard.
The library supports saving and loading cache data to and from files using Gob encoding, allowing the cache state to be persisted and restored
To use go-cache in your project, install it using the following Go command:
go get github.com/pzentenoe/go-cacheImport go-cache in your project:
import "github.com/pzentenoe/go-cache"package main
import (
"fmt"
"time"
"github.com/pzentenoe/go-cache"
)
func main() {
// Create a cache with a default expiration time of 5 minutes, and which
// purges expired items every 10 minutes
c := cache.New(5*time.Minute, 10*time.Minute)
// Set the value of the key "key1" to "value1", with the default expiration time
c.Set("key1", "value1", cache.DefaultExpiration)
val, found := c.Get("key1")
if found {
fmt.Println("Found value:", val)
} else {
fmt.Println("Item not found")
}
c.SaveFile("cache.data")
c.LoadFile("cache.data")
}package main
import (
"fmt"
"time"
"github.com/pzentenoe/go-cache"
)
func main() {
// Create a sharded cache with a default expiration time of 5 minutes, and which
// purges expired items every 10 minutes
sc := cache.NewSharded(5*time.Minute, 10*time.Minute, 10)
sc.Set("key1", "value1", cache.DefaultExpiration)
val, found := sc.Get("key1")
if found {
fmt.Println("Found value:", val)
} else {
fmt.Println("Item not found")
}
sc.SaveFile("sharded_cache.data")
sc.LoadFile("sharded_cache.data")
}package main
import (
"fmt"
"time"
"github.com/pzentenoe/go-cache"
)
func main() {
c := cache.New(5*time.Minute, 10*time.Minute)
c.Set("counter", 1, cache.DefaultExpiration)
c.Increment("counter", 1)
val, _ := c.Get("counter")
fmt.Println("Counter after increment:", val)
c.Decrement("counter", 1)
val, _ = c.Get("counter")
fmt.Println("Counter after decrement:", val)
}Set(k string, x any, d time.Duration)Adds an item to the cache, replacing any existing item. If the duration is DefaultExpiration, the cache’s default expiration time is used. If it is NoExpiration, the item never expires.
SetDefault(k string, x any)Adds an item to the cache using the default expiration time.
Add(k string, x any, d time.Duration) errorAdds an item to the cache only if an item doesn’t already exist for the given key, or if the existing item has expired. Returns an error otherwise.
Replace(k string, x any, d time.Duration) errorSets a new value for the cache key only if it already exists, and the existing item hasn’t expired. Returns an error otherwise.
Get(k string) (any, bool)Gets an item from the cache. Returns the item or nil, and a boolean indicating whether the key was found.
GetWithExpiration(k string) (any, time.Time, bool)Returns an item and its expiration time from the cache. If the item never expires, a zero value for time.Time is returned.
Delete(k string)Deletes an item from the cache.
DeleteExpired()Deletes all expired items from the cache.
OnEvicted(f func(string, any))Sets a function that is called with the key and value when an item is evicted from the cache. Set to nil to disable.
Flush()Deletes all items from the cache.
Increment(k string, n int64) errorIncrements an item of type int, int8, int16, int32, int64, uintptr, uint, uint8, uint32, or uint64, float32, or float64 by n. Returns an error if the item’s value is not an integer or if it was not found.
IncrementFloat(k string, n float64) errorIncrements an item of type float32 or float64 by n. Returns an error if the item’s value is not floating point, if it was not found, or if it is not possible to increment it by n.
Decrement(k string, n int64) errorDecrements an item of type int, int8, int16, int32, int64, uintptr, uint, uint8, uint32, or uint64, float32, or float64 by n. Returns an error if the item’s value is not an integer or if it was not found.
DecrementFloat(k string, n float64) errorDecrements an item of type float32 or float64 by n. Returns an error if the item’s value is not floating point, if it was not found, or if it is not possible to decrement it by n.
Items() map[string]ItemCopies all unexpired items in the cache into a new map and returns it.
ItemCount() intReturns the number of items in the cache. This may include items that have expired but have not yet been cleaned up.
Save(w io.Writer) errorWrites the cache’s items (using Gob) to an io.Writer.
SaveFile(fname string) errorSaves the cache’s items to the given filename, creating the file if it doesn’t exist and overwriting it if it does.
Load(r io.Reader) errorAdds (Gob-serialized) cache items from an io.Reader, excluding any items with keys that already exist (and haven’t expired) in the current cache.
LoadFile(fname string) errorLoads and adds cache items from the given filename, excluding any items with keys that already exist in the current cache.
Execute the tests with:
go test ./...We welcome contributions! Please fork the project and submit pull requests to the main branch. Make sure to add tests
for new functionalities and document any significant changes.
This project is released under the MIT License. See the LICENSE file for more details.
For a detailed changelog, refer to CHANGELOG.md.
- Pablo Zenteno - Full Stack Developer - pzentenoe