gcache

package module
v2.0.0+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 6, 2017 License: MIT Imports: 5 Imported by: 0

README

GCache

wercker statusGoDoc

Cache library for golang. It supports expirable Cache, LFU, LRU and ARC.

Features

  • Supports expirable Cache, LFU, LRU and ARC.

  • Goroutine safe.

  • Supports event handlers which evict and add entry. (Optional)

  • Automatically load cache if it doesn't exists. (Optional)

Install

$ go get github.com/bluele/gcache

Example

Manually set a key-value pair.
package main

import (
  "github.com/bluele/gcache"
  "fmt"
)

func main() {
  gc := gcache.New(20).
    LRU().
    Build()
  gc.Set("key", "ok")
  value, err := gc.Get("key")
  if err != nil {
    panic(err)
  }
  fmt.Println("Get:", value)
}

Get: ok
Automatically load value
package main

import (
  "github.com/bluele/gcache"
  "fmt"
)

func main() {
  gc := gcache.New(20).
    LRU().
    LoaderFunc(func(key interface{}) (interface{}, error) {
      return "ok", nil
    }).
    Build()
  value, err := gc.Get("key")
  if err != nil {
    panic(err)
  }
  fmt.Println("Get:", value)
}

Get: ok

Cache Algorithm

  • Least-Frequently Used (LFU)

Discards the least frequently used items first.

func main() {
  // size: 10
  gc := gcache.New(10).
    LFU().
    Build()
  gc.Set("key", "value")
}
  • Least Recently Used (LRU)

Discards the least recently used items first.

func main() {
  // size: 10
  gc := gcache.New(10).
    LRU().
    Build()
  gc.Set("key", "value")
}
  • Adaptive Replacement Cache (ARC)

Constantly balances between LRU and LFU, to improve the combined result.

detail: http://en.wikipedia.org/wiki/Adaptive_replacement_cache

func main() {
  // size: 10
  gc := gcache.New(10).
    ARC().
    Build()
  gc.Set("key", "value")
}
  • SimpleCache (Default)

SimpleCache has no clear priority for evict cache. It depends on key-value map order.

func main() {
  // size: 10
  gc := gcache.New(10).Build()
  gc.Set("key", "value")
  v, err := gc.Get("key")
  if err != nil {
    panic(err)
  }
}

Loading Cache

If specified LoaderFunc, values are automatically loaded by the cache, and are stored in the cache until either evicted or manually invalidated.

func main() {
  gc := gcache.New(10).
    LRU().
    LoaderFunc(func(key interface{}) (interface{}, error) {
      return "value", nil
    }).
    Build()
  v, _ := gc.Get("key")
  // output: "value"
  fmt.Println(v)
}

GCache coordinates cache fills such that only one load in one process of an entire replicated set of processes populates the cache, then multiplexes the loaded value to all callers.

Expirable cache

func main() {
  // LRU cache, size: 10, expiration: after a hour
  gc := gcache.New(10).
    LRU().
    Expiration(time.Hour).
    Build()
}

Event handlers

Evicted handler

Event handler for evict the entry.

func main() {
  gc := gcache.New(2).
    EvictedFunc(func(key, value interface{}) {
      fmt.Println("evicted key:", key)
    }).
    Build()
  for i := 0; i < 3; i++ {
    gc.Set(i, i*i)
  }
}

evicted key: 0
Added handler

Event handler for add the entry.

func main() {
  gc := gcache.New(2).
    AddedFunc(func(key, value interface{}) {
      fmt.Println("added key:", key)
    }).
    Build()
  for i := 0; i < 3; i++ {
    gc.Set(i, i*i)
  }
}

added key: 0
added key: 1
added key: 2

Author

Jun Kimura

Documentation

Index

Constants

View Source 
const (
	TYPE_SIMPLE = "simple"
	TYPE_LRU    = "lru"
	TYPE_LFU    = "lfu"
	TYPE_ARC    = "arc"
)

Variables

View Source 
var KeyNotFoundError = errors.New("Key not found.")

Functions

This section is empty.

Types

type ARC 

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

Constantly balances between LRU and LFU, to improve the combined result.

func (*ARC) Get 

func (c *ARC) Get(key interface{}) (interface{}, error)

Get a value from cache pool using key if it exists. If not exists and it has LoaderFunc, it will generate the value using you have specified LoaderFunc method returns value.

func (*ARC) GetALL 

func (c *ARC) GetALL() map[interface{}]interface{}

Returns all key-value pairs in the cache.

func (*ARC) GetIFPresent 

func (c *ARC) GetIFPresent(key interface{}) (interface{}, error)

Get a value from cache pool using key if it exists. If it dose not exists key, returns KeyNotFoundError. And send a request which refresh value for specified key if cache object has LoaderFunc.

func (*ARC) Keys 

func (c *ARC) Keys() []interface{}

Keys returns a slice of the keys in the cache.

func (*ARC) Len 

func (c *ARC) Len() int

Len returns the number of items in the cache.

func (*ARC) Purge 

func (c *ARC) Purge()

Purge is used to completely clear the cache

func (*ARC) Remove 

func (c *ARC) Remove(key interface{}) bool

Remove removes the provided key from the cache.

func (*ARC) Set 

func (c *ARC) Set(key, value interface{})

type AddedFunc 

type AddedFunc func(interface{}, interface{})

type Cache 

type Cache interface {
	Set(interface{}, interface{})
	Get(interface{}) (interface{}, error)
	GetIFPresent(interface{}) (interface{}, error)
	GetALL() map[interface{}]interface{}

	Remove(interface{}) bool
	Purge()
	Keys() []interface{}
	Len() int
	// contains filtered or unexported methods
}

type CacheBuilder 

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

func New 

func New(size int) *CacheBuilder

func (*CacheBuilder) ARC 

func (cb *CacheBuilder) ARC() *CacheBuilder

func (*CacheBuilder) AddedFunc 

func (cb *CacheBuilder) AddedFunc(addedFunc AddedFunc) *CacheBuilder

func (*CacheBuilder) Build 

func (cb *CacheBuilder) Build() Cache

func (*CacheBuilder) EvictType 

func (cb *CacheBuilder) EvictType(tp string) *CacheBuilder

func (*CacheBuilder) EvictedFunc 

func (cb *CacheBuilder) EvictedFunc(evictedFunc EvictedFunc) *CacheBuilder

func (*CacheBuilder) Expiration 

func (cb *CacheBuilder) Expiration(expiration time.Duration) *CacheBuilder

func (*CacheBuilder) LFU 

func (cb *CacheBuilder) LFU() *CacheBuilder

func (*CacheBuilder) LRU 

func (cb *CacheBuilder) LRU() *CacheBuilder

func (*CacheBuilder) LoaderFunc 

func (cb *CacheBuilder) LoaderFunc(loaderFunc LoaderFunc) *CacheBuilder

Set a loader function. loaderFunc: create a new value with this function if cached value is expired.

func (*CacheBuilder) Simple 

func (cb *CacheBuilder) Simple() *CacheBuilder

type EvictedFunc 

type EvictedFunc func(interface{}, interface{})

type Group 

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

Group represents a class of work and forms a namespace in which units of work can be executed with duplicate suppression.

func (*Group) Do 

func (g *Group) Do(key interface{}, fn func() (interface{}, error), isWait bool) (interface{}, bool, error)

Do executes and returns the results of the given function, making sure that only one execution is in-flight for a given key at a time. If a duplicate comes in, the duplicate caller waits for the original to complete and receives the same results.

type LFUCache 

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

Discards the least frequently used items first.

func (*LFUCache) Get 

func (c *LFUCache) Get(key interface{}) (interface{}, error)

Get a value from cache pool using key if it exists. If it dose not exists key and has LoaderFunc, generate a value using `LoaderFunc` method returns value.

func (*LFUCache) GetALL 

func (c *LFUCache) GetALL() map[interface{}]interface{}

Returns all key-value pairs in the cache.

func (*LFUCache) GetIFPresent 

func (c *LFUCache) GetIFPresent(key interface{}) (interface{}, error)

Get a value from cache pool using key if it exists. If it dose not exists key, returns KeyNotFoundError. And send a request which refresh value for specified key if cache object has LoaderFunc.

func (*LFUCache) Keys 

func (c *LFUCache) Keys() []interface{}

Returns a slice of the keys in the cache.

func (*LFUCache) Len 

func (c *LFUCache) Len() int

Returns the number of items in the cache.

func (*LFUCache) Purge 

func (c *LFUCache) Purge()

Completely clear the cache

func (*LFUCache) Remove 

func (c *LFUCache) Remove(key interface{}) bool

Removes the provided key from the cache.

func (*LFUCache) Set 

func (c *LFUCache) Set(key, value interface{})

set a new key-value pair

type LRUCache 

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

Discards the least recently used items first.

func (*LRUCache) Get 

func (c *LRUCache) Get(key interface{}) (interface{}, error)

Get a value from cache pool using key if it exists. If it dose not exists key and has LoaderFunc, generate a value using `LoaderFunc` method returns value.

func (*LRUCache) GetALL 

func (c *LRUCache) GetALL() map[interface{}]interface{}

Returns all key-value pairs in the cache.

func (*LRUCache) GetIFPresent 

func (c *LRUCache) GetIFPresent(key interface{}) (interface{}, error)

Get a value from cache pool using key if it exists. If it dose not exists key, returns KeyNotFoundError. And send a request which refresh value for specified key if cache object has LoaderFunc.

func (*LRUCache) Keys 

func (c *LRUCache) Keys() []interface{}

Returns a slice of the keys in the cache.

func (*LRUCache) Len 

func (c *LRUCache) Len() int

Returns the number of items in the cache.

func (*LRUCache) Purge 

func (c *LRUCache) Purge()

Completely clear the cache

func (*LRUCache) Remove 

func (c *LRUCache) Remove(key interface{}) bool

Removes the provided key from the cache.

func (*LRUCache) Set 

func (c *LRUCache) Set(key, value interface{})

set a new key-value pair

type LoaderFunc 

type LoaderFunc func(interface{}) (interface{}, error)

type SimpleCache 

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

SimpleCache has no clear priority for evict cache. It depends on key-value map order.

func (*SimpleCache) Get 

func (c *SimpleCache) Get(key interface{}) (interface{}, error)

Get a value from cache pool using key if it exists. If it dose not exists key and has LoaderFunc, generate a value using `LoaderFunc` method returns value.

func (*SimpleCache) GetALL 

func (c *SimpleCache) GetALL() map[interface{}]interface{}

Returns all key-value pairs in the cache.

func (*SimpleCache) GetIFPresent 

func (c *SimpleCache) GetIFPresent(key interface{}) (interface{}, error)

Get a value from cache pool using key if it exists. If it dose not exists key, returns KeyNotFoundError. And send a request which refresh value for specified key if cache object has LoaderFunc.

func (*SimpleCache) Keys 

func (c *SimpleCache) Keys() []interface{}

Returns a slice of the keys in the cache.

func (*SimpleCache) Len 

func (c *SimpleCache) Len() int

Returns the number of items in the cache.

func (*SimpleCache) Purge 

func (c *SimpleCache) Purge()

Completely clear the cache

func (*SimpleCache) Remove 

func (c *SimpleCache) Remove(key interface{}) bool

Removes the provided key from the cache.

func (*SimpleCache) Set 

func (c *SimpleCache) Set(key, value interface{})

set a new key-value pair

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.