cachego

Overview ¶

Package cachego provides an easy way to use foundation for your caching operations.

1. basic:

// Use NewCache function to create a cache.
// By default, it creates a standard cache which evicts entries randomly.
// Use WithShardings to shard cache to several parts for higher performance.
// Use WithGC to clean expired entries every 10 minutes.
cache := cachego.NewCache(cachego.WithGC(10*time.Minute), cachego.WithShardings(64))

// Set an entry to cache with ttl.
cache.Set("key", 123, time.Second)

// Get an entry from cache.
value, ok := cache.Get("key")
fmt.Println(value, ok) // 123 true

// Check how many entries stores in cache.
size := cache.Size()
fmt.Println(size) // 1

// Clean expired entries.
cleans := cache.GC()
fmt.Println(cleans) // 1

// Set an entry which doesn't have ttl.
cache.Set("key", 123, cachego.NoTTL)

// Remove an entry.
removedValue := cache.Remove("key")
fmt.Println(removedValue) // 123

// Reset resets cache to initial status.
cache.Reset()

// Get value from cache and load it to cache if not found.
value, ok = cache.Get("key")
if !ok {
	// Loaded entry will be set to cache and returned.
	// By default, it will use singleflight.
	value, _ = cache.Load("key", time.Second, func() (value interface{}, err error) {
		return 666, nil
	})
}

fmt.Println(value) // 666

// You can use WithLRU to specify the type of cache to lru.
// Also, try WithLFU if you want to use lfu to evict data.
cache = cachego.NewCache(cachego.WithLRU(100))
cache = cachego.NewCache(cachego.WithLFU(100))

// Use NewCacheWithReport to create a cache with report.
cache, reporter := cachego.NewCacheWithReport(cachego.WithCacheName("test"))
fmt.Println(reporter.CacheName())
fmt.Println(reporter.CacheType())

2. ttl:

cache := cachego.NewCache()

// We think most of the entries in cache should have its ttl.
// So set an entry to cache should specify a ttl.
cache.Set("key", 666, time.Second)

value, ok := cache.Get("key")
fmt.Println(value, ok) // 666 true

time.Sleep(2 * time.Second)

// The entry is expired after ttl.
value, ok = cache.Get("key")
fmt.Println(value, ok) // <nil> false

// Notice that the entry still stores in cache even if it's expired.
// This is because we think you will reset entry to cache after cache missing in most situations.
// So we can reuse this entry and just reset its value and ttl.
size := cache.Size()
fmt.Println(size) // 1

// What should I do if I want an expired entry never storing in cache? Try GC:
cleans := cache.GC()
fmt.Println(cleans) // 1

size = cache.Size()
fmt.Println(size) // 0

// However, not all entries have ttl, and you can specify a NoTTL constant to do so.
// In fact, the entry won't expire as long as its ttl is <= 0.
// So you may have known NoTTL is a "readable" value of "<= 0".
cache.Set("key", 666, cachego.NoTTL)

3. lru:

// By default, NewCache() returns a standard cache which evicts entries randomly.
cache := cachego.NewCache(cachego.WithMaxEntries(10))

for i := 0; i < 20; i++ {
	key := strconv.Itoa(i)
	cache.Set(key, i, cachego.NoTTL)
}

// Since we set 20 entries to cache, the size won't be 20 because we limit the max entries to 10.
size := cache.Size()
fmt.Println(size) // 10

// We don't know which entries will be evicted and stayed.
for i := 0; i < 20; i++ {
	key := strconv.Itoa(i)
	value, ok := cache.Get(key)
	fmt.Println(key, value, ok)
}

fmt.Println()

// Sometimes we want it evicts entries by lru, try WithLRU.
// You need to specify the max entries storing in lru cache.
// More details see https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU).
cache = cachego.NewCache(cachego.WithLRU(10))

for i := 0; i < 20; i++ {
	key := strconv.Itoa(i)
	cache.Set(key, i, cachego.NoTTL)
}

// Only the least recently used entries can be got in a lru cache.
for i := 0; i < 20; i++ {
	key := strconv.Itoa(i)
	value, ok := cache.Get(key)
	fmt.Println(key, value, ok)
}

// By default, lru will share one lock to do all operations.
// You can sharding cache to several parts for higher performance.
// Notice that max entries only effect to one part in sharding mode.
// For example, the total max entries will be 2*10 if shardings is 2 and max entries is 10 in WithLRU or WithMaxEntries.
// In some cache libraries, they will calculate max entries in each parts of shardings, like 10/2.
// However, the result divided by max entries and shardings may be not an integer which will make the total max entries incorrect.
// So we let users decide the exact max entries in each parts of shardings.
cache = cachego.NewCache(cachego.WithShardings(2), cachego.WithLRU(10))

4. lfu:

// By default, NewCache() returns a standard cache which evicts entries randomly.
cache := cachego.NewCache(cachego.WithMaxEntries(10))

for i := 0; i < 20; i++ {
	key := strconv.Itoa(i)
	cache.Set(key, i, cachego.NoTTL)
}

// Since we set 20 entries to cache, the size won't be 20 because we limit the max entries to 10.
size := cache.Size()
fmt.Println(size) // 10

// We don't know which entries will be evicted and stayed.
for i := 0; i < 20; i++ {
	key := strconv.Itoa(i)
	value, ok := cache.Get(key)
	fmt.Println(key, value, ok)
}

fmt.Println()

// Sometimes we want it evicts entries by lfu, try WithLFU.
// You need to specify the max entries storing in lfu cache.
// More details see https://en.wikipedia.org/wiki/Cache_replacement_policies#Least-frequently_used_(LFU).
cache = cachego.NewCache(cachego.WithLFU(10))

for i := 0; i < 20; i++ {
	key := strconv.Itoa(i)

	// Let entries have some frequently used operations.
	for j := 0; j < i; j++ {
		cache.Set(key, i, cachego.NoTTL)
	}
}

for i := 0; i < 20; i++ {
	key := strconv.Itoa(i)
	value, ok := cache.Get(key)
	fmt.Println(key, value, ok)
}

// By default, lfu will share one lock to do all operations.
// You can sharding cache to several parts for higher performance.
// Notice that max entries only effect to one part in sharding mode.
// For example, the total max entries will be 2*10 if shardings is 2 and max entries is 10 in WithLFU or WithMaxEntries.
// In some cache libraries, they will calculate max entries in each parts of shardings, like 10/2.
// However, the result divided by max entries and shardings may be not an integer which will make the total max entries incorrect.
// So we let users decide the exact max entries in each parts of shardings.
cache = cachego.NewCache(cachego.WithShardings(2), cachego.WithLFU(10))

5. sharding:

// All operations in cache share one lock for concurrency.
// Use read lock or write lock is depends on cache implements.
// Get will use read lock in standard cache, but lru and lfu don't.
// This may be a serious performance problem in high qps.
cache := cachego.NewCache()

// We provide a sharding cache wrapper to shard one cache to several parts with hash.
// Every parts store its entries and all operations of one entry work on one part.
// This means there are more than one lock when you operate entries.
// The performance will be better in high qps.
cache = cachego.NewCache(cachego.WithShardings(64))
cache.Set("key", 666, cachego.NoTTL)

value, ok := cache.Get("key")
fmt.Println(value, ok) // 666 true

// Notice that max entries will be the sum of shards.
// For example, we set WithShardings(4) and WithMaxEntries(100), and the max entries in whole cache will be 4 * 100.
cache = cachego.NewCache(cachego.WithShardings(4), cachego.WithMaxEntries(100))

for i := 0; i < 1000; i++ {
	key := strconv.Itoa(i)
	cache.Set(key, i, cachego.NoTTL)
}

size := cache.Size()
fmt.Println(size) // 400

6. gc:

cache := cachego.NewCache()
cache.Set("key", 666, time.Second)

time.Sleep(2 * time.Second)

// The entry is expired after ttl.
value, ok := cache.Get("key")
fmt.Println(value, ok) // <nil> false

// As you know the entry still stores in cache even if it's expired.
// This is because we think you will reset entry to cache after cache missing in most situations.
// So we can reuse this entry and just reset its value and ttl.
size := cache.Size()
fmt.Println(size) // 1

// What should I do if I want an expired entry never storing in cache? Try GC:
cleans := cache.GC()
fmt.Println(cleans) // 1

// Is there a smart way to do that? Try WithGC:
// For testing, we set a small duration of gc.
// You should set at least 3 minutes in production for performance.
cache = cachego.NewCache(cachego.WithGC(2 * time.Second))
cache.Set("key", 666, time.Second)

size = cache.Size()
fmt.Println(size) // 1

time.Sleep(3 * time.Second)

size = cache.Size()
fmt.Println(size) // 0

// Or you want a cancalable gc task? Try RunGCTask:
cache = cachego.NewCache()
cancel := cachego.RunGCTask(cache, 2*time.Second)

cache.Set("key", 666, time.Second)

size = cache.Size()
fmt.Println(size) // 1

time.Sleep(3 * time.Second)

size = cache.Size()
fmt.Println(size) // 0

cancel()

cache.Set("key", 666, time.Second)

size = cache.Size()
fmt.Println(size) // 1

time.Sleep(3 * time.Second)

size = cache.Size()
fmt.Println(size) // 1

// By default, gc only scans at most maxScans entries one time to remove expired entries.
// This is because scans all entries may cost much time if there is so many entries in cache, and a "stw" will happen.
// This can be a serious problem in some situations.
// Use WithMaxScans to set this value, remember, a value <= 0 means no scan limit.
cache = cachego.NewCache(cachego.WithGC(10*time.Minute), cachego.WithMaxScans(0))

7. load:

// By default, singleflight is enabled in cache.
// Use WithDisableSingleflight to disable if you want.
cache := cachego.NewCache(cachego.WithDisableSingleflight())

// We recommend you to use singleflight.
cache = cachego.NewCache()

value, ok := cache.Get("key")
fmt.Println(value, ok) // <nil> false

if !ok {
	// Load loads a value of key to cache with ttl.
	// Use cachego.NoTTL if you want this value is no ttl.
	// After loading value to cache, it returns the loaded value and error if failed.
	value, _ = cache.Load("key", time.Second, func() (value interface{}, err error) {
		return 666, nil
	})
}

fmt.Println(value) // 666

value, ok = cache.Get("key")
fmt.Println(value, ok) // 666, true

time.Sleep(2 * time.Second)

value, ok = cache.Get("key")
fmt.Println(value, ok) // <nil>, false

8. report:

func reportMissed(reporter *cachego.Reporter, key string) {
	fmt.Printf("report: missed key %s, missed rate %.3f\n", key, reporter.MissedRate())
}

func reportHit(reporter *cachego.Reporter, key string, value interface{}) {
	fmt.Printf("report: hit key %s value %+v, hit rate %.3f\n", key, value, reporter.HitRate())
}

func reportGC(reporter *cachego.Reporter, cost time.Duration, cleans int) {
	fmt.Printf("report: gc cost %s cleans %d, gc count %d, cache size %d\n", cost, cleans, reporter.CountGC(), reporter.CacheSize())
}

func reportLoad(reporter *cachego.Reporter, key string, value interface{}, ttl time.Duration, err error) {
	fmt.Printf("report: load key %s value %+v ttl %s, err %+v, load count %d\n", key, value, ttl, err, reporter.CountLoad())
}

// We provide some ways to report the status of cache.
// Use NewCacheWithReport to create a cache with reporting features.
cache, reporter := cachego.NewCacheWithReport(
	// Sometimes you may have several caches in one service.
	// You can set each name by WithCacheName and get the name from reporter.
	cachego.WithCacheName("test"),

	// For testing...
	cachego.WithMaxEntries(3),
	cachego.WithGC(100*time.Millisecond),

	// ReportMissed reports the missed key getting from cache.
	// ReportHit reports the hit entry getting from cache.
	// ReportGC reports the status of cache gc.
	// ReportLoad reports the result of loading.
	cachego.WithReportMissed(reportMissed),
	cachego.WithReportHit(reportHit),
	cachego.WithReportGC(reportGC),
	cachego.WithReportLoad(reportLoad),
)

for i := 0; i < 5; i++ {
	key := strconv.Itoa(i)
	evictedValue := cache.Set(key, key, 10*time.Millisecond)
	fmt.Println(evictedValue)
}

for i := 0; i < 5; i++ {
	key := strconv.Itoa(i)
	value, ok := cache.Get(key)
	fmt.Println(value, ok)
}

time.Sleep(200 * time.Millisecond)

value, err := cache.Load("key", time.Second, func() (value interface{}, err error) {
	return 666, io.EOF
})

fmt.Println(value, err)

// These are some useful methods of reporter.
fmt.Println("CacheName:", reporter.CacheName())
fmt.Println("CacheType:", reporter.CacheType())
fmt.Println("CountMissed:", reporter.CountMissed())
fmt.Println("CountHit:", reporter.CountHit())
fmt.Println("CountGC:", reporter.CountGC())
fmt.Println("CountLoad:", reporter.CountLoad())
fmt.Println("CacheSize:", reporter.CacheSize())
fmt.Println("MissedRate:", reporter.MissedRate())
fmt.Println("HitRate:", reporter.HitRate())

9. task:

var (
	contextKey = struct{}{}
)

func beforePrint(ctx context.Context) {
	fmt.Println("before:", ctx.Value(contextKey))
}

func afterPrint(ctx context.Context) {
	fmt.Println("after:", ctx.Value(contextKey))
}

func printContextValue(ctx context.Context) {
	fmt.Println("context value:", ctx.Value(contextKey))
}

// Create a context to stop the task.
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

// Wrap context with key and value
ctx = context.WithValue(ctx, contextKey, "hello")

// Use New to create a task and run it.
// You can use it to load some hot data to cache at fixed duration.
// Before is called before the task loop, optional.
// After is called after the task loop, optional.
// Context is passed to fn include fn/before/after which can stop the task by Done(), optional.
// Duration is the duration between two loop of fn, optional.
// Run will start a new goroutine and run the task loop.
// The task will stop if context is done.
task.New(printContextValue).Before(beforePrint).After(afterPrint).Context(ctx).Duration(time.Second).Run()

10. clock:

// Create a fast clock and get current time in nanosecond by Now.
c := clock.New()
c.Now()

// Fast clock may return an "incorrect" time compared with time.Now.
// The gap will be smaller than about 100 ms.
for i := 0; i < 10; i++ {
	time.Sleep(time.Duration(rand.Int63n(int64(time.Second))))

	timeNow := time.Now().UnixNano()
	clockNow := c.Now()

	fmt.Println(timeNow)
	fmt.Println(clockNow)
	fmt.Println("gap:", time.Duration(timeNow-clockNow))
	fmt.Println()
}

// You can specify the fast clock to cache by WithNow.
// All getting current time operations in this cache will use fast clock.
cache := cachego.NewCache(cachego.WithNow(clock.New().Now))
cache.Set("key", 666, 100*time.Millisecond)

value, ok := cache.Get("key")
fmt.Println(value, ok) // 666, true

time.Sleep(200 * time.Millisecond)

value, ok = cache.Get("key")
fmt.Println(value, ok) // <nil>, false