Cache

README

Redis cache library for Golang

go-redis/cache is brought to you by ⭐ uptrace/uptrace. Uptrace is an open source and blazingly fast distributed tracing tool powered by OpenTelemetry and ClickHouse. Give it a star as well!

go-redis/cache library implements a cache using Redis as a key/value storage. It uses MessagePack to marshal values.

Optionally, you can use TinyLFU or any other cache algorithm as a local in-process cache.

If you are interested in monitoring cache hit rate, see the guide for Monitoring using OpenTelemetry Metrics.

Installation

go-redis/cache supports 2 last Go versions and requires a Go version with modules support. So make sure to initialize a Go module:

go mod init github.com/my/repo

And then install go-redis/cache/v8 (note v8 in the import; omitting it is a popular mistake):

go get github.com/go-redis/cache/v8

Quickstart

package cache_test

import (
"context"
"fmt"
"time"

"github.com/go-redis/redis/v8"
"github.com/go-redis/cache/v8"
)

type Object struct {
Str string
Num int
}

func Example_basicUsage() {
ring := redis.NewRing(&redis.RingOptions{
Addrs: map[string]string{
"server1": ":6379",
"server2": ":6380",
},
})

mycache := cache.New(&cache.Options{
Redis:      ring,
LocalCache: cache.NewTinyLFU(1000, time.Minute),
})

ctx := context.TODO()
key := "mykey"
obj := &Object{
Str: "mystring",
Num: 42,
}

if err := mycache.Set(&cache.Item{
Ctx:   ctx,
Key:   key,
Value: obj,
TTL:   time.Hour,
}); err != nil {
panic(err)
}

var wanted Object
if err := mycache.Get(ctx, key, &wanted); err == nil {
fmt.Println(wanted)
}

// Output: {mystring 42}
}

func Example_advancedUsage() {
ring := redis.NewRing(&redis.RingOptions{
Addrs: map[string]string{
"server1": ":6379",
"server2": ":6380",
},
})

mycache := cache.New(&cache.Options{
Redis:      ring,
LocalCache: cache.NewTinyLFU(1000, time.Minute),
})

obj := new(Object)
err := mycache.Once(&cache.Item{
Key:   "mykey",
Value: obj, // destination
Do: func(*cache.Item) (interface{}, error) {
return &Object{
Str: "mystring",
Num: 42,
}, nil
},
})
if err != nil {
panic(err)
}
fmt.Println(obj)
// Output: &{mystring 42}
}

Documentation

Index

• Variables
• type Cache
  • func GetDefaultUniversalClient(addrs []string) *Cache
  • func New(opt *Options) *Cache
  • func (cd *Cache) Delete(ctx context.Context, key string) error
  • func (cd *Cache) Exists(ctx context.Context, key string) bool
  • func (cd *Cache) Get(ctx context.Context, key string, value interface{}) error
  • func (cd *Cache) Marshal(value interface{}) ([]byte, error)
  • func (cd *Cache) Once(item *Item) error
  • func (cd *Cache) Set(item *Item) error
  • func (cd *Cache) Stats() *Stats
  • func (cd *Cache) Unmarshal(b []byte, value interface{}) error
• type Item
  • func (item *Item) Context() context.Context
• type MarshalFunc
• type Options
• type Stats
• type UnmarshalFunc

Variables

var (
	ErrCacheMiss = errors.New("cache: key is missing")
)

Types

type Cache

type Cache struct {
	// contains filtered or unexported fields
}

func GetDefaultUniversalClient

func GetDefaultUniversalClient(addrs []string) *Cache

func New

func New(opt *Options) *Cache

func (*Cache) Delete

func (cd *Cache) Delete(ctx context.Context, key string) error

func (*Cache) Exists

func (cd *Cache) Exists(ctx context.Context, key string) bool

Exists reports whether value for the given key exists.

func (*Cache) Get

func (cd *Cache) Get(ctx context.Context, key string, value interface{}) error

Get gets the value for the given key.

func (*Cache) Marshal

func (cd *Cache) Marshal(value interface{}) ([]byte, error)

func (*Cache) Once

func (cd *Cache) Once(item *Item) error

Once gets the item.Value for the given item.Key from the cache or executes, caches, and returns the results of the given item.Func, 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) Set

func (cd *Cache) Set(item *Item) error

Set caches the item.

func (*Cache) Stats

func (cd *Cache) Stats() *Stats

Stats returns cache statistics.

func (*Cache) Unmarshal

func (cd *Cache) Unmarshal(b []byte, value interface{}) error

type Item

type Item struct {
	Ctx context.Context

	Key   string
	Value interface{}

	// TTL is the cache expiration time.
	// Default TTL is 1 hour.
	TTL time.Duration

	// Do returns value to be cached.
	Do func(*Item) (interface{}, error)

	// SetXX only sets the key if it already exists.
	SetXX bool

	// SetNX only sets the key if it does not already exist.
	SetNX bool
}

func (*Item) Context

func (item *Item) Context() context.Context

type MarshalFunc

type MarshalFunc func(interface{}) ([]byte, error)

------------------------------------------------------------------------------

type Options

type Options struct {
	Redis        rediser
	StatsEnabled bool
	Marshal      MarshalFunc
	Unmarshal    UnmarshalFunc
}

type Stats

type Stats struct {
	Hits   uint64
	Misses uint64
}

type UnmarshalFunc

type UnmarshalFunc func([]byte, interface{}) error

------------------------------------------------------------------------------