README
¶
cache
Cache using Go 1.18 generics.
cache is an in-memory key:value store/cache similar to memcached that is
suitable for applications running on a single machine.
import (
"fmt"
"github.com/alaingilbert/cache"
)
func main() {
// Create a cache of "string" with a default expiration time of 5 minutes
// and which purges expired items every 10 minutes (DefaultCleanupInterval)
// The cleanup interval can be changed for a custom value using "CleanupInterval"
// `cache.New[string](5*time.Minute, cache.CleanupInterval(time.Hour))`
// The cleanup thread can be terminated using a context.Context
// `cache.New[string](5*time.Minute, cache.WithContext(ctx))`
c := cache.New[string](5*time.Minute)
// Set the value of the key "key1" to "val1", with the default expiration time (5min)
c.Set("key1", "val1")
// Set the value of the key "key2" to "val2", with a 1sec expiration time
c.Set("key2", "val2", cache.ExpireIn(time.Second))
// Set the value of the key "key3" to "val3", which will expire on Jan 01 2100
c.Set("key3", "val3", cache.ExpireAt(time.Date(2100, 1, 1, 0, 0, 0, 0, time.Local)))
// Set the value of the key "key4" to "val4", with no expiration time
// (the item won't be removed until it is re-set, or removed using
// c.Delete("key4")
c.Set("key4", "val4", cache.NoExpire)
// Return either or not "key1" is in the cache and not expired
found := c.Has("key1")
// Get the string associated with the key "key1" from the cache
if value, found := c.Get("key1"); found {
fmt.Println(value)
}
// Delete "key1" from the cache
c.Delete("key1")
// Can also use a "Set" (data structure) for cache
s := cache.NewSet[string](5*time.Minute)
s.Set("key1")
if s.Has("key1") {
fmt.Println("found key1")
}
s.Delete("key1")
}
Documentation
¶
Index ¶
- Constants
- Variables
- func GetCast[T any, K comparable](c *Cache[K, any], k K) (value T, ok bool)
- func GetCastInto[T any, K comparable](c *Cache[K, any], k K, into *T) bool
- func GetTryCast[T any, K comparable](c *Cache[K, any], k K) (ok bool)
- func NoExpire(cfg *ItemConfig)
- type Cache
- func (c *Cache[K, V]) Add(k K, v V, opts ...ItemOption) error
- func (c *Cache[K, V]) Delete(k K)
- func (c *Cache[K, V]) DeleteAll()
- func (c *Cache[K, V]) DeleteExpired()
- func (c *Cache[K, V]) Destroy()
- func (c *Cache[K, V]) Get(k K) (value V, found bool)
- func (c *Cache[K, V]) GetWithExpiration(k K) (value V, expiration time.Time, found bool)
- func (c *Cache[K, V]) Has(k K) (found bool)
- func (c *Cache[K, V]) Items() map[K]Item[V]
- func (c *Cache[K, V]) Len() int
- func (c *Cache[K, V]) Replace(k K, v V, opts ...ItemOption) error
- func (c *Cache[K, V]) Set(k K, v V, opts ...ItemOption)
- func (c *Cache[K, V]) Take(k K) (value V, found bool)
- type Config
- type Item
- type ItemConfig
- type ItemOption
- type Option
- type SetCache
- func (s *SetCache[K]) Add(k K, opts ...ItemOption) error
- func (s *SetCache[K]) Delete(k K)
- func (s *SetCache[K]) DeleteAll()
- func (s *SetCache[K]) DeleteExpired()
- func (s *SetCache[K]) Destroy()
- func (s *SetCache[K]) GetExpiration(k K) (expiration time.Time, found bool)
- func (s *SetCache[K]) Has(k K) bool
- func (s *SetCache[K]) Len() int
- func (s *SetCache[K]) Replace(k K, opts ...ItemOption) error
- func (s *SetCache[K]) Set(k K, opts ...ItemOption)
Constants ¶
const ( // NoExpiration ... NoExpiration time.Duration = -1 // DefaultExpiration ... DefaultExpiration time.Duration = 0 )
Variables ¶
var DefaultCleanupInterval = 10 * time.Minute
DefaultCleanupInterval is exported so that someone could override the value in their project
var ErrItemAlreadyExists = errors.New("item already exists")
ErrItemAlreadyExists ...
var ErrItemNotFound = errors.New("item does not exists")
ErrItemNotFound ...
Functions ¶
func GetCast ¶
func GetCast[T any, K comparable](c *Cache[K, any], k K) (value T, ok bool)
GetCast ...
func GetCastInto ¶
func GetCastInto[T any, K comparable](c *Cache[K, any], k K, into *T) bool
GetCastInto ...
func GetTryCast ¶
func GetTryCast[T any, K comparable](c *Cache[K, any], k K) (ok bool)
GetTryCast useful if you want to test if a key exists and is of a specific type `if GetTryCast[int](c, "someKey") {`
Types ¶
type Cache ¶
type Cache[K comparable, V any] struct { // contains filtered or unexported fields }
Cache ...
func NewWithKey ¶
NewWithKey creates a cache with a custom comparable K provided by the user
func (*Cache[K, V]) Add ¶
func (c *Cache[K, V]) Add(k K, v V, opts ...ItemOption) error
Add 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.
func (*Cache[K, V]) DeleteAll ¶
func (c *Cache[K, V]) DeleteAll()
DeleteAll deletes all items from the cache
func (*Cache[K, V]) DeleteExpired ¶
func (c *Cache[K, V]) DeleteExpired()
DeleteExpired deletes all expired items from the cache
func (*Cache[K, V]) Destroy ¶
func (c *Cache[K, V]) Destroy()
Destroy the cache object, cleanup all resources
func (*Cache[K, V]) GetWithExpiration ¶
GetWithExpiration gets a value and its expiration time from the cache. If the item never expires a zero value for time.Time is returned.
func (*Cache[K, V]) Items ¶
Items copies all unexpired items in the cache into a new map and returns it.
func (*Cache[K, V]) Len ¶
Len returns the number of items in the cache. This may include items that have expired, but have not yet been cleaned up.
func (*Cache[K, V]) Replace ¶
func (c *Cache[K, V]) Replace(k K, v V, opts ...ItemOption) error
Replace set a new value for the cache key only if it already exists, and the existing item hasn't expired. Returns an error otherwise.
func (*Cache[K, V]) Set ¶
func (c *Cache[K, V]) Set(k K, v V, opts ...ItemOption)
Set a key/value pair in the cache
type Config ¶
type Config struct {
// contains filtered or unexported fields
}
Config ...
func (*Config) CleanupInterval ¶
CleanupInterval ...
type Item ¶
type Item[V any] struct { // contains filtered or unexported fields }
Item wrap the user provided value and add data to it
func (Item[V]) Expiration ¶
Expiration returns the expiration time
type ItemConfig ¶
type ItemConfig struct {
// contains filtered or unexported fields
}
ItemConfig ...
func (*ItemConfig) Duration ¶
func (c *ItemConfig) Duration(d time.Duration) *ItemConfig
Duration ...
type ItemOption ¶
type ItemOption func(cfg *ItemConfig)
ItemOption ...
func ExpireIn ¶
func ExpireIn(d time.Duration) ItemOption
ExpireIn can be used to override the default expiration for a key when calling the Add/Set/Replace methods
type Option ¶
type Option func(cfg *Config)
Option ...
func CleanupInterval ¶
CleanupInterval changes the cleanup interval
type SetCache ¶
type SetCache[K comparable] struct { // contains filtered or unexported fields }
SetCache ...
func NewSet ¶
func NewSet[K comparable](defaultExpiration time.Duration, opts ...Option) *SetCache[K]
NewSet creates a new "set" cache
func (*SetCache[K]) Add ¶
func (s *SetCache[K]) Add(k K, opts ...ItemOption) error
func (*SetCache[K]) DeleteExpired ¶
func (s *SetCache[K]) DeleteExpired()
func (*SetCache[K]) GetExpiration ¶
func (*SetCache[K]) Replace ¶
func (s *SetCache[K]) Replace(k K, opts ...ItemOption) error
func (*SetCache[K]) Set ¶
func (s *SetCache[K]) Set(k K, opts ...ItemOption)
Source Files
Directories