cache

README

Redis cache library for Golang

❤ Uptrace.dev - distributed traces, logs, and errors in one place

Installation

go-redis/cache requires a Go version with Modules support and uses import versioning. So please make sure to initialize a Go module before installation:

go mod init github.com/my/repo
go get -u 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

Overview

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}

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}

Index

• Variables
• type 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) GetSkippingLocalCache(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 LocalCache
• type Options
• type Stats
• type TinyLFU
  • func NewTinyLFU(size int, ttl time.Duration) *TinyLFU
  • func (c *TinyLFU) Del(key string)
  • func (c *TinyLFU) Get(key string) ([]byte, bool)
  • func (c *TinyLFU) Set(key string, b []byte)
  • func (c *TinyLFU) UseRandomizedTTL(offset time.Duration)

Examples

• Package (AdvancedUsage)
• Package (BasicUsage)

Variables

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

Types

type Cache

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

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) GetSkippingLocalCache

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

Get gets the value for the given key skipping local cache.

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

	// SkipLocalCache skips local cache as if it is not set.
	SkipLocalCache bool
}

func (*Item) Context

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

type LocalCache

type LocalCache interface {
	Set(key string, data []byte)
	Get(key string) ([]byte, bool)
	Del(key string)
}

type Options

type Options struct {
	Redis        rediser
	LocalCache   LocalCache
	StatsEnabled bool
}

type Stats

type Stats struct {
	Hits   uint64
	Misses uint64
}

type TinyLFU

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

func NewTinyLFU

func NewTinyLFU(size int, ttl time.Duration) *TinyLFU

func (*TinyLFU) Del

func (c *TinyLFU) Del(key string)

func (*TinyLFU) Get

func (c *TinyLFU) Get(key string) ([]byte, bool)

func (*TinyLFU) Set

func (c *TinyLFU) Set(key string, b []byte)

func (*TinyLFU) UseRandomizedTTL

func (c *TinyLFU) UseRandomizedTTL(offset time.Duration)