cache

README

Redis cache library for Golang

Installation

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

Quickstart

package cache_test

import (
	"fmt"
	"time"

	"github.com/go-redis/redis"
	"github.com/vmihailenco/msgpack"

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

type Object struct {
	Str string
	Num int
}

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

	codec := &cache.Codec{
		Redis: ring,

		Marshal: func(v interface{}) ([]byte, error) {
			return msgpack.Marshal(v)
		},
		Unmarshal: func(b []byte, v interface{}) error {
			return msgpack.Unmarshal(b, v)
		},
	}

	key := "mykey"
	obj := &Object{
		Str: "mystring",
		Num: 42,
	}

	codec.Set(&cache.Item{
		Key:        key,
		Object:     obj,
		Expiration: time.Hour,
	})

	var wanted Object
	if err := codec.Get(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",
		},
	})

	codec := &cache.Codec{
		Redis: ring,

		Marshal: func(v interface{}) ([]byte, error) {
			return msgpack.Marshal(v)
		},
		Unmarshal: func(b []byte, v interface{}) error {
			return msgpack.Unmarshal(b, v)
		},
	}

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

Documentation

Overview

Example (AdvancedUsage)

package main

import (
	"fmt"

	"github.com/go-redis/redis"
	"github.com/vmihailenco/msgpack"

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

type Object struct {
	Str string
	Num int
}

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

	codec := &cache.Codec{
		Redis: ring,

		Marshal: func(v interface{}) ([]byte, error) {
			return msgpack.Marshal(v)
		},
		Unmarshal: func(b []byte, v interface{}) error {
			return msgpack.Unmarshal(b, v)
		},
	}

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

Output:

&{mystring 42}

Example (BasicUsage)

package main

import (
	"fmt"
	"time"

	"github.com/go-redis/redis"
	"github.com/vmihailenco/msgpack"

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

type Object struct {
	Str string
	Num int
}

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

	codec := &cache.Codec{
		Redis: ring,

		Marshal: func(v interface{}) ([]byte, error) {
			return msgpack.Marshal(v)
		},
		Unmarshal: func(b []byte, v interface{}) error {
			return msgpack.Unmarshal(b, v)
		},
	}

	key := "mykey"
	obj := &Object{
		Str: "mystring",
		Num: 42,
	}

	codec.Set(&cache.Item{
		Key:        key,
		Object:     obj,
		Expiration: time.Hour,
	})

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

}

Output:

{mystring 42}

Index

• Variables
• func SetLogger(logger internal.Logger)
• type Codec
  • func (cd *Codec) AddHook(h Hook)
  • func (cd *Codec) Delete(key string) error
  • func (cd *Codec) DeleteContext(c context.Context, key string) error
  • func (cd *Codec) Exists(key string) bool
  • func (cd *Codec) Get(key string, object interface{}) error
  • func (cd *Codec) GetContext(c context.Context, key string, object interface{}) error
  • func (cd *Codec) Once(item *Item) error
  • func (cd *Codec) Set(item *Item) error
  • func (cd *Codec) Stats() *Stats
  • func (cd *Codec) UseLocalCache(maxLen int, expiration time.Duration)
• type Hook
• type Item
• type Stats

Examples

• Package (AdvancedUsage)
• Package (BasicUsage)

Variables

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

Functions

func SetLogger

func SetLogger(logger internal.Logger)

Types

type Codec

type Codec struct {
	Redis rediser

	Marshal   func(interface{}) ([]byte, error)
	Unmarshal func([]byte, interface{}) error
	// contains filtered or unexported fields
}

func (*Codec) AddHook

func (cd *Codec) AddHook(h Hook)

func (*Codec) Delete

func (cd *Codec) Delete(key string) error

func (*Codec) DeleteContext

func (cd *Codec) DeleteContext(c context.Context, key string) error

func (*Codec) Exists

func (cd *Codec) Exists(key string) bool

Exists reports whether object for the given key exists.

func (*Codec) Get

func (cd *Codec) Get(key string, object interface{}) error

Get gets the object for the given key.

func (*Codec) GetContext

func (cd *Codec) GetContext(c context.Context, key string, object interface{}) error

func (*Codec) Once

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

Once gets the item.Object 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 (*Codec) Set

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

Set caches the item.

func (*Codec) Stats

func (cd *Codec) Stats() *Stats

Stats returns cache statistics.

func (*Codec) UseLocalCache

func (cd *Codec) UseLocalCache(maxLen int, expiration time.Duration)

UseLocalCache causes Codec to cache items in local LRU cache.

type Hook

type Hook interface {
	BeforeSet(item *Item) error
	AfterSet(item *Item) error

	BeforeGet(c context.Context, key string, object interface{}) (context.Context, error)
	AfterGet(c context.Context, key string, object interface{}) (context.Context, error)

	BeforeDelete(c context.Context, key string) (context.Context, error)
	AfterDelete(c context.Context, key string) (context.Context, error)

	BeforeOnce(item *Item) error
	AfterOnce(item *Item) error
}

type Item

type Item struct {
	Ctx context.Context

	Key    string
	Object interface{}

	// Func returns object to be cached.
	Func func() (interface{}, error)

	// Expiration is the cache expiration time.
	// Default expiration is 1 hour.
	Expiration time.Duration
}

type Stats

type Stats struct {
	Hits        uint64
	Misses      uint64
	LocalHits   uint64
	LocalMisses uint64
}