README
¶
Cache library for Go
Right now this project is under constraction.
This project was started as a fork of go-cache, but later I decided to rewrite it.
How to test
For launching all tests a redis instance required
WITH_REDIS="redis://localhost:6379" make test
or create file named .env.local with next content
WITH_REDIS=redis://localhost:6379
and run tests by
make test
If this redis instance is in production, tests should be pointed to another redis db on this instance, like
WITH_REDIS=redis://localhost:6379/1
In this case tests will use first and next redis databases (assuming db 0 contains production data). Tests use more databases, starting from db of connection.
Documentation
¶
Overview ¶
Example (AdvancedUsage) ¶
rdb := MustNewRedisCmdable()
mycache := cache.New().WithNamespace("expx-cache-v0:").
WithTinyLFU(1000, time.Hour).WithRedis(rdb)
var obj Object
if err := mycache.Once(context.Background(), cache.Item{
Key: "mykey2",
Value: &obj, // destination
Do: func(ctx context.Context) (any, error) {
return Object{Str: "mystring2", Num: 42}, nil
},
}); err != nil {
log.Fatal(err)
}
fmt.Println(obj)
Output: {mystring2 42}
Example (BasicUsage) ¶
rdb := MustNewRedisCmdable()
mycache := cache.New().WithNamespace("expx-cache-v0:").
WithTinyLFU(1000, time.Hour).WithRedis(rdb)
ctx := context.Background()
key := "mykey1"
obj := Object{Str: "mystring1", Num: 42}
item := cache.Item{Key: key, Value: &obj}
if err := mycache.Set(ctx, item); err != nil {
log.Fatal(err)
}
var wanted Object
item.Value = &wanted
if missed, err := mycache.Get(ctx, item); err != nil {
log.Fatal(err)
} else if len(missed) == 0 {
fmt.Println(wanted)
} else {
fmt.Println("not found")
}
Output: {mystring1 42}
Index ¶
- Variables
- type Cache
- func (self *Cache) DefaultTTL() time.Duration
- func (self *Cache) Delete(ctx context.Context, keys ...string) error
- func (self *Cache) DeleteFromLocalCache(keys ...string)
- func (self *Cache) DeleteFromRedis(ctx context.Context, keys ...string) error
- func (self *Cache) Err() error
- func (self *Cache) Exists(ctx context.Context, key string) (bool, error)
- func (self *Cache) Get(ctx context.Context, items ...Item) ([]Item, error)
- func (self *Cache) GetSet(ctx context.Context, items ...Item) error
- func (self *Cache) Marshal(value any) ([]byte, error)
- func (self *Cache) Namespace() string
- func (self *Cache) New(opts ...Option) *Cache
- func (self *Cache) Once(ctx context.Context, item Item) error
- func (self *Cache) OnceLock(ctx context.Context, item Item) error
- func (self *Cache) ResetErr() error
- func (self *Cache) ResolveKey(key string) string
- func (self *Cache) ResolveKeyLock(key string) string
- func (self *Cache) Set(ctx context.Context, items ...Item) error
- func (self *Cache) Stats() Stats
- func (self *Cache) Unmarshal(b []byte, value any) error
- func (self *Cache) WithDefaultTTL(ttl time.Duration) *Cache
- func (self *Cache) WithItemMaxProcs(n int) *Cache
- func (self *Cache) WithKeyWrapper(fn func(key string) string) *Cache
- func (self *Cache) WithLocalCache(client LocalCache) *Cache
- func (self *Cache) WithLocalStats(fn func(c *Cache) error, opts ...Option) (Stats, error)
- func (self *Cache) WithMarshal(fn MarshalFunc) *Cache
- func (self *Cache) WithNamespace(namespace string) *Cache
- func (self *Cache) WithPrefixLock(s string) *Cache
- func (self *Cache) WithRedis(rdb redis.Cmdable) *Cache
- func (self *Cache) WithRedisCache(client RedisCache) *Cache
- func (self *Cache) WithRequestId(id string) *Cache
- func (self *Cache) WithStats(val bool) *Cache
- func (self *Cache) WithTinyLFU(size int, ttl time.Duration) *Cache
- func (self *Cache) WithUnmarshal(fn UnmarshalFunc) *Cache
- func (self *Cache) WrapKey(key string) string
- type Item
- type LocalCache
- type MarshalFunc
- type Option
- type RedisCache
- type RedisCacheError
- type Stats
- type UnmarshalFunc
- type WaitLockIter
Examples ¶
Constants ¶
This section is empty.
Variables ¶
View Source
var ErrRedisCache = newRedisCacheError(errors.New("redis cache error"))
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
func New ¶
Example ¶
rdb := MustNewRedisCmdable()
mycache := cache.New(
cache.WithLock(10*time.Second, 3*time.Second, func() cache.WaitLockIter {
return cache.NewWaitLockIter(time.Second, 10*time.Second)
})).
WithDefaultTTL(24*time.Hour).
WithStats(true).
WithNamespace("expx-cache-v0:").
WithTinyLFU(1000, time.Hour).WithRedis(rdb)
fmt.Println(mycache.ResolveKey("mykey3"))
Output: expx-cache-v0:mykey3
func (*Cache) DefaultTTL ¶
func (*Cache) Delete ¶
Example ¶
rdb := MustNewRedisCmdable()
mycache := cache.New().WithNamespace("expx-cache-v0:").
WithTinyLFU(1000, time.Hour).WithRedis(rdb)
if err := mycache.Delete(
context.Background(), "mykey1", "mykey2", "mykey3", "mykey4", "mykey5",
); err != nil {
log.Fatal(err)
}
Output:
func (*Cache) DeleteFromLocalCache ¶
func (*Cache) DeleteFromRedis ¶
func (*Cache) Exists ¶
Exists reports whether value for the given key exists.
Example ¶
rdb := MustNewRedisCmdable()
mycache := cache.New().WithTinyLFU(1000, time.Hour).WithRedis(rdb)
ok, err := mycache.Exists(context.Background(), "mykey1")
if err != nil {
log.Fatal(err)
}
fmt.Println(ok)
mycache.WithNamespace("expx-cache-v0:")
ok, err = mycache.Exists(context.Background(), "mykey1")
if err != nil {
log.Fatal(err)
}
fmt.Println(ok)
Output: false true
func (*Cache) Get ¶
Example ¶
rdb := MustNewRedisCmdable()
mycache := cache.New().WithNamespace("expx-cache-v0:").
WithTinyLFU(1000, time.Hour).WithRedis(rdb)
var value1, value2 Object
missed, err := mycache.Get(context.Background(),
cache.Item{Key: "mykey1", Value: &value1},
cache.Item{Key: "mykey2", Value: &value2},
cache.Item{Key: "mykey3"},
)
if err != nil {
log.Fatal(err)
}
fmt.Println("missed:", len(missed), missed[0].Key)
fmt.Println("value1:", value1)
fmt.Println("value2:", value2)
Output: missed: 1 mykey3 value1: {mystring1 42} value2: {mystring2 42}
func (*Cache) GetSet ¶
Example ¶
rdb := MustNewRedisCmdable()
mycache := cache.New().WithNamespace("expx-cache-v0:").
WithTinyLFU(1000, time.Hour).WithRedis(rdb)
var value1, value2 Object
err := mycache.GetSet(context.Background(),
cache.Item{
Key: "mykey1",
Value: &value1,
Do: func(ctx context.Context) (any, error) {
return Object{Str: "mystring1", Num: 42}, nil
},
},
cache.Item{
Key: "mykey5",
Value: &value2,
Do: func(ctx context.Context) (any, error) {
return Object{Str: "mystring5", Num: 42}, nil
},
},
)
if err != nil {
log.Fatal(err)
}
fmt.Println("value1:", value1)
fmt.Println("value2:", value2)
Output: value1: {mystring1 42} value2: {mystring5 42}
func (*Cache) Once ¶
Once gets the item.Value for the given item.Key from the cache or executes, caches, and returns the results of the given item.Do, making sure that only one execution is in-flight for a given item.Key at a time. If a duplicate comes in, the duplicate caller waits for the original to complete and receives the same results.
func (*Cache) OnceLock ¶
Example ¶
rdb := MustNewRedisCmdable()
mycache := cache.New().WithNamespace("expx-cache-v0:").
WithTinyLFU(1000, time.Hour).WithRedis(rdb)
var obj Object
if err := mycache.OnceLock(context.Background(), cache.Item{
Key: "mykey1",
Value: &obj, // destination
Do: func(ctx context.Context) (any, error) {
return Object{Str: "mystring6", Num: 42}, nil
},
}); err != nil {
log.Fatal(err)
}
fmt.Println(obj)
Output: {mystring1 42}
func (*Cache) ResolveKey ¶
func (*Cache) ResolveKeyLock ¶
func (*Cache) Set ¶
Set caches the item.
Example ¶
rdb := MustNewRedisCmdable()
mycache := cache.New().WithNamespace("expx-cache-v0:").
WithTinyLFU(1000, time.Hour).WithRedis(rdb)
value1 := Object{Str: "mystring3", Num: 42}
value2 := Object{Str: "mystring4", Num: 42}
err := mycache.Set(context.Background(),
cache.Item{Key: "mykey3", Value: &value1},
cache.Item{Key: "mykey4", Value: &value2},
)
fmt.Println(err)
Output: <nil>
func (*Cache) WithItemMaxProcs ¶
func (*Cache) WithLocalCache ¶
func (self *Cache) WithLocalCache(client LocalCache) *Cache
func (*Cache) WithLocalStats ¶
func (*Cache) WithMarshal ¶
func (self *Cache) WithMarshal(fn MarshalFunc) *Cache
func (*Cache) WithNamespace ¶
func (*Cache) WithPrefixLock ¶
func (*Cache) WithRedisCache ¶
func (self *Cache) WithRedisCache(client RedisCache) *Cache
func (*Cache) WithRequestId ¶
func (*Cache) WithUnmarshal ¶
func (self *Cache) WithUnmarshal(fn UnmarshalFunc) *Cache
type Item ¶
type Item struct {
Key string
Value any
// TTL is the cache expiration time.
// Default TTL configured using [WithDefaultTTL] and it's 1 hour by default.
TTL time.Duration
// Do returns value to be cached.
Do func(ctx context.Context) (any, error)
// SkipLocalCache skips local cache as if it is not set.
SkipLocalCache bool
}
type LocalCache ¶
type MarshalFunc ¶
type Option ¶
type Option func(c *Cache)
func WithItemMaxProcs ¶
func WithLockNotFound ¶
func WithMarshalMaxProcs ¶
type RedisCache ¶
type RedisCache interface {
Del(ctx context.Context, keys []string) error
Get(ctx context.Context, maxItems int,
keyIter func(itemIdx int) string) (func() ([]byte, bool), error)
Set(ctx context.Context, maxItems int,
iter func(itemIdx int) (key string, b []byte, ttl time.Duration)) error
LockGet(ctx context.Context, keySet, value string, ttl time.Duration,
keyGet string) (ok bool, b []byte, err error)
Expire(ctx context.Context, key string, ttl time.Duration) (bool, error)
Unlock(ctx context.Context, key, value string) (bool, error)
Listen(ctx context.Context, key string, ready ...func() error) (string, error)
}
type RedisCacheError ¶
type RedisCacheError struct {
// contains filtered or unexported fields
}
func (*RedisCacheError) Is ¶
func (self *RedisCacheError) Is(target error) bool
func (*RedisCacheError) Unwrap ¶
func (self *RedisCacheError) Unwrap() error
type UnmarshalFunc ¶
type WaitLockIter ¶
func NewWaitLockIter ¶
func NewWaitLockIter(start time.Duration, seq ...time.Duration) WaitLockIter
Source Files
¶
Directories
Click to show internal directories.
Click to hide internal directories.