gache

README

gache is thinnest cache library for go application

Requirement

Go 1.11

Installation

go get github.com/kpango/gache

Example

	// data sets
	var (
		key1 = "key"
		key2 = 5050
		key3 = struct{}{}

		value1 = "value"
		value2 = 88888
		value3 = struct{}{}
	)

	// store cache default expire is 30 Seconds
	gache.Set(key1, value3)
	gache.Set(key2, value2)
	gache.Set(key3, value1)

	// load cache data
	v1, ok := gache.Get(key1)

	v2, ok := gache.Get(key2)

	v3, ok := gache.Get(key3)


	gache.Write(context.Background(), glg.FileWriter("./gache-sample.gdb", 0755))
	gache.New().SetDefaultExpire(time.Minute).Read(glg.FileWriter("./gache-sample.gdb", 0755))

Benchmarks

gache vs gocache vs normal map with lock vs go-cache vs gcache vs freecache vs bigcache vs go-mcache

go test -count=1 -run=NONE -bench . -benchmem

goos: darwin
goarch: amd64
pkg: github.com/kpango/gache
BenchmarkGacheWithSmallDataset-8       	 5000000	       250 ns/op	     192 B/op	       8 allocs/op
BenchmarkGacheWithBigDataset-8         	     500	   3179552 ns/op	  485156 B/op	   20160 allocs/op
BenchmarkGocacheWithSmallDataset-8     	 3000000	       378 ns/op	     323 B/op	      16 allocs/op
BenchmarkGocacheWithBigDataset-8       	     300	   3564275 ns/op	  815303 B/op	   40352 allocs/op
BenchmarkFastCacheWithSmallDataset-8   	 1000000	      1496 ns/op	      44 B/op	       4 allocs/op
BenchmarkFastCacheWithBigDataset-8     	      50	  36815105 ns/op	126848505 B/op	   41603 allocs/op
BenchmarkBigCacheWithSmallDataset-8    	 1000000	      1915 ns/op	     424 B/op	       8 allocs/op
BenchmarkBigCacheWithBigDataset-8      	      30	  62743673 ns/op	227737772 B/op	   32892 allocs/op
BenchmarkFreeCacheWithSmallDataset-8   	 1000000	      2659 ns/op	      31 B/op	       4 allocs/op
BenchmarkFreeCacheWithBigDataset-8     	      50	  26550884 ns/op	126889120 B/op	   41552 allocs/op
BenchmarkMapWithSmallDataset-8         	  500000	      4221 ns/op	     137 B/op	       8 allocs/op
BenchmarkMapWithBigDataset-8           	     100	  10926857 ns/op	  358593 B/op	   20808 allocs/op
BenchmarkGoCacheWithSmallDataset-8     	  500000	      3870 ns/op	      73 B/op	       4 allocs/op
BenchmarkGoCacheWithBigDataset-8       	     100	  10858366 ns/op	  201482 B/op	   10809 allocs/op
BenchmarkGCacheLRUWithSmallDataset-8   	  200000	      7913 ns/op	     348 B/op	      16 allocs/op
BenchmarkGCacheLRUWithBigDataset-8     	      50	  21157440 ns/op	 2026806 B/op	   61756 allocs/op
BenchmarkGCacheLFUWithSmallDataset-8   	  200000	     10704 ns/op	     542 B/op	      20 allocs/op
BenchmarkGCacheLFUWithBigDataset-8     	      50	  22017917 ns/op	 1491388 B/op	   51602 allocs/op
BenchmarkGCacheARCWithSmallDataset-8   	  200000	     10987 ns/op	     350 B/op	      16 allocs/op
BenchmarkGCacheARCWithBigDataset-8     	      20	  64480186 ns/op	 3068799 B/op	   84008 allocs/op
BenchmarkMCacheWithSmallDataset-8      	  100000	     18578 ns/op	    4373 B/op	      41 allocs/op
BenchmarkMCacheWithBigDataset-8        	      30	  34827645 ns/op	10851422 B/op	  102187 allocs/op
BenchmarkBitcaskWithSmallDataset-8     	   30000	     55917 ns/op	    2455 B/op	      49 allocs/op
BenchmarkBitcaskWithBigDataset-8       	     200	  10602661 ns/op	10502332 B/op	   11091 allocs/op
PASS
ok  	github.com/kpango/gache	67.249s

Contribution

1. Fork it ( https://github.com/kpango/gache/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Author

kpango

LICENSE

gache released under MIT license, refer LICENSE file.

Documentation

Index

• func Clear()
• func Delete(key string) (val interface{}, loaded bool)
• func DeleteExpired(ctx context.Context) uint64
• func Get(key string) (interface{}, bool)
• func GetWithExpire(key string) (interface{}, int64, bool)
• func Len() int
• func Read(r io.Reader) error
• func Set(key string, val interface{})
• func SetWithExpire(key string, val interface{}, expire time.Duration)
• func Stop()
• func ToMap(ctx context.Context) *sync.Map
• func ToRawMap(ctx context.Context) map[string]interface{}
• func Write(ctx context.Context, w io.Writer) error
• type Gache
  • func DisableExpiredHook() Gache
  • func EnableExpiredHook() Gache
  • func Foreach(ctx context.Context, f func(string, interface{}, int64) bool) Gache
  • func GetGache() Gache
  • func New(opts ...Option) Gache
  • func SetDefaultExpire(ex time.Duration) Gache
  • func SetExpiredHook(f func(context.Context, string)) Gache
• type Map
  • func (m *Map) Delete(key string)
  • func (m *Map) Load(key string) (value value, ok bool)
  • func (m *Map) LoadAndDelete(key string) (value value, loaded bool)
  • func (m *Map) Range(f func(key string, value value) bool)
  • func (m *Map) Store(key string, value value)
• type Option
  • func WithDefaultExpiration(dur time.Duration) Option
  • func WithDefaultExpirationString(t string) Option
  • func WithExpiredHookFunc(f func(ctx context.Context, key string)) Option

Functions

func Clear

func Clear()

Clear deletes all key and value present in the Gache.

func Delete

func Delete(key string) (val interface{}, loaded bool)

Delete deletes value from Gache using key

func DeleteExpired

func DeleteExpired(ctx context.Context) uint64

DeleteExpired deletes expired value from Gache it can be cancel using context

func Get

func Get(key string) (interface{}, bool)

Get returns value & exists from key

func GetWithExpire

func GetWithExpire(key string) (interface{}, int64, bool)

GetWithExpire returns value & expire & exists from key

func Len

func Len() int

Len returns stored object length

func Read

func Read(r io.Reader) error

Read reads reader data to cache

func Set

func Set(key string, val interface{})

Set sets key-value to Gache using default expiration

func SetWithExpire

func SetWithExpire(key string, val interface{}, expire time.Duration)

SetWithExpire sets key-value & expiration to Gache

func Stop

func Stop()

Stop kills expire daemon

func ToMap

func ToMap(ctx context.Context) *sync.Map

ToMap returns All Cache Key-Value sync.Map

func ToRawMap

func ToRawMap(ctx context.Context) map[string]interface{}

ToRawMap returns All Cache Key-Value map

func Write

func Write(ctx context.Context, w io.Writer) error

Write writes all cached data to writer

Types

type Gache

type Gache interface {
	Clear()
	Delete(string) (interface{}, bool)
	DeleteExpired(context.Context) uint64
	DisableExpiredHook() Gache
	EnableExpiredHook() Gache
	Foreach(context.Context, func(string, interface{}, int64) bool) Gache
	Get(string) (interface{}, bool)
	GetWithExpire(string) (interface{}, int64, bool)
	Read(io.Reader) error
	Set(string, interface{})
	SetDefaultExpire(time.Duration) Gache
	SetExpiredHook(f func(context.Context, string)) Gache
	SetWithExpire(string, interface{}, time.Duration)
	StartExpired(context.Context, time.Duration) Gache
	Len() int
	ToMap(context.Context) *sync.Map
	ToRawMap(context.Context) map[string]interface{}
	Write(context.Context, io.Writer) error
	Stop()
}

Gache is base interface type

func DisableExpiredHook

func DisableExpiredHook() Gache

DisableExpiredHook disables expired hook function

func EnableExpiredHook

func EnableExpiredHook() Gache

EnableExpiredHook enables expired hook function

func Foreach

func Foreach(ctx context.Context, f func(string, interface{}, int64) bool) Gache

Foreach calls f sequentially for each key and value present in the Gache.

func GetGache

func GetGache() Gache

GetGache returns Gache (*gache) instance

func New

func New(opts ...Option) Gache

New returns Gache (*gache) instance

func SetDefaultExpire

func SetDefaultExpire(ex time.Duration) Gache

SetDefaultExpire set expire duration

func SetExpiredHook

func SetExpiredHook(f func(context.Context, string)) Gache

SetExpiredHook set expire hooked function

type Map

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

func (*Map) Delete

func (m *Map) Delete(key string)

func (*Map) Load

func (m *Map) Load(key string) (value value, ok bool)

func (*Map) LoadAndDelete

func (m *Map) LoadAndDelete(key string) (value value, loaded bool)

func (*Map) Range

func (m *Map) Range(f func(key string, value value) bool)

func (*Map) Store

func (m *Map) Store(key string, value value)

type Option

type Option func(g *gache) error

func WithDefaultExpiration

func WithDefaultExpiration(dur time.Duration) Option

func WithDefaultExpirationString

func WithDefaultExpirationString(t string) Option

func WithExpiredHookFunc

func WithExpiredHookFunc(f func(ctx context.Context, key string)) Option