libcache

README

Libcache

A Lightweight in-memory key:value cache library for Go.

Introduction

Caches are tremendously useful in a wide variety of use cases.
you should consider using caches when a value is expensive to compute or retrieve,
and you will need its value on a certain input more than once.
libcache is here to help with that.

Libcache are local to a single run of your application.
They do not store data in files, or on outside servers.

Libcache previously an go-guardian package and designed to be a companion with it.
While both can operate completely independently.

Features

• Rich caching API
• Maximum cache size enforcement
• Default cache TTL (time-to-live) as well as custom TTLs per cache entry
• Thread safe as well as non-thread safe
• Event-Driven callbacks (OnExpired,OnEvicted)
• Dynamic cache creation
• Multiple cache replacement policies:
  • FIFO (First In, First Out)
  • LIFO (Last In, First Out)
  • LRU (Least Recently Used)
  • MRU (Most Recently Used)
  • LFU (Least Frequently Used)
  • ARC (Adaptive Replacement Cache)

Quickstart

Installing

Using libcache is easy. First, use go get to install the latest version of the library.

go get github.com/shaj13/libcache

Next, include libcache in your application:

import (
    _ "github.com/shaj13/libcache/<desired-replacement-policy>"
    "github.com/shaj13/libcache"
)

Examples

Note: All examples use the LRU cache replacement policy for simplicity, any other cache replacement policy can be applied to them.

Basic

package main 
import (
    "fmt" 

    "github.com/shaj13/libcache"
    _ "github.com/shaj13/libcache/lru"
)

func main() {
    size := 10
    cache := libcache.LRU.NewUnsafe(size)
    for i:= 0 ; i < 10 ; i++ {
        cache.Store(i, i)
    }
    fmt.Println(cache.Load(0)) // nil, false  
    fmt.Println(cache.Load(1)) // 1, true
}

Thread Safe

package main

import (
	"fmt"

	"github.com/shaj13/libcache"
	_ "github.com/shaj13/libcache/lru"
)

func main() {
	done := make(chan struct{})

	f := func(c libcache.Cache) {
		for !c.Contains(5) {
		}
		fmt.Println(c.Load(5)) // 5, true
		done <- struct{}{}
	}

	size := 10
	cache := libcache.LRU.New(size)
	go f(cache)

	for i := 0; i < 10; i++ {
		cache.Store(i, i)
	}

	<-done
}

Unlimited Size

zero capacity means cache has no limit and replacement policy turned off.

package main 
import (
    "fmt" 

    "github.com/shaj13/libcache"
    _ "github.com/shaj13/libcache/lru"
)

func main() {
	cache := libcache.LRU.New(0)
    for i:= 0 ; i < 100000 ; i++ {
        cache.Store(i, i)
    }
	fmt.Println(cache.Load(55555))
}

TTL

package main 
import (
	"fmt"
	"time"

	"github.com/shaj13/libcache"
	_ "github.com/shaj13/libcache/lru"
)

func main() {
	cache := libcache.LRU.New(10)
	cache.SetTTL(time.Second) // default TTL 
	
	for i:= 0 ; i < 10 ; i++ {
        cache.Store(i, i)
	}
	fmt.Println(cache.Expiry(1))

	cache.StoreWithTTL("mykey", "value", time.Hour) // TTL per cache entry 
	fmt.Println(cache.Expiry("mykey"))

}

Events

Timed expiration by default is performed with lazy maintenance during reads operations,
Evict an expired entry immediately can be done using on expired callback.
You may also specify a eviction listener for your cache to perform some operation when an entry is evicted.
Note: Expiration events relying on golang runtime timers heap to call on expired callback when an entry TTL elapsed.

package main 
import (
	"fmt"
	"time"

	"github.com/shaj13/libcache"
	_ "github.com/shaj13/libcache/lru"
)

func main() {
	cache := libcache.LRU.New(10)
	cache.RegisterOnEvicted(func(key, value interface{}) {
		fmt.Printf("Cache Key %v Evicted\n", key)
	})

	cache.RegisterOnExpired(func(key, value interface{}) {
		fmt.Printf("Cache Key %v Expired, Removing it from cache\n", key)
		// use delete directly when your application 
		// guarantee no other goroutine can store items with the same key.
		// Peek also invoke lazy expiry. 
		// 
		// Note this should done only with safe cache.
		cache.Peek(key) 
	})	

	for i:= 0 ; i < 10 ; i++ {
        cache.StoreWithTTL(i, i, time.Microsecond)
	}

	time.Sleep(time.Second)
	fmt.Println(cache.Len())
}

Contributing

1. Fork it
2. Download your fork to your PC (git clone https://github.com/your_username/libcache && cd libcache)
3. Create your feature branch (git checkout -b my-new-feature)
4. Make changes and add them (git add .)
5. Commit your changes (git commit -m 'Add some feature')
6. Push to the branch (git push origin my-new-feature)
7. Create new pull request

License

Libcache is released under the MIT license. See LICENSE

Documentation

Overview

Package libcache provides in-memory caches based on different caches replacement algorithms.

Index

• type Cache
• type ReplacementPolicy
  • func (c ReplacementPolicy) Available() bool
  • func (c ReplacementPolicy) New(cap int) Cache
  • func (c ReplacementPolicy) NewUnsafe(cap int) Cache
  • func (c ReplacementPolicy) Register(function func(cap int) Cache)
  • func (c ReplacementPolicy) String() string

Types

type Cache

type Cache interface {
	// Load returns key value.
	Load(key interface{}) (interface{}, bool)
	// Peek returns key value without updating the underlying "recent-ness".
	Peek(key interface{}) (interface{}, bool)
	// Update the key value without updating the underlying "recent-ness".
	Update(key interface{}, value interface{})
	// Store sets the key value.
	Store(key interface{}, value interface{})
	// StoreWithTTL sets the key value with TTL overrides the default.
	StoreWithTTL(key interface{}, value interface{}, ttl time.Duration)
	// Delete deletes the key value.
	Delete(key interface{})
	// Expiry returns key value expiry time.
	Expiry(key interface{}) (time.Time, bool)
	// Keys return cache records keys.
	Keys() []interface{}
	// Contains Checks if a key exists in cache.
	Contains(key interface{}) bool
	// Purge Clears all cache entries.
	Purge()
	// Resize cache, returning number evicted
	Resize(int) int
	// Len Returns the number of items in the cache.
	Len() int
	// Cap Returns the cache capacity.
	Cap() int
	// TTL returns entries default TTL.
	TTL() time.Duration
	// SetTTL sets entries default TTL.
	SetTTL(time.Duration)
	// RegisterOnEvicted registers a function,
	// to call in its own goroutine when an entry is purged from the cache.
	RegisterOnEvicted(f func(key, value interface{}))
	// RegisterOnExpired registers a function,
	// to call in its own goroutine when an entry TTL elapsed.
	// invocation of f, does not mean the entry is purged from the cache,
	// if need be, it must coordinate with the cache explicitly.
	//
	// 	var cache cache.Cache
	// 	onExpired := func(key, value interface{}) {
	//	 	_, _, _ = cache.Peek(key)
	// 	}
	//
	// This should not be done unless the cache thread-safe.
	RegisterOnExpired(f func(key, value interface{}))
}

Cache stores data so that future requests for that data can be served faster.

type ReplacementPolicy

type ReplacementPolicy uint

ReplacementPolicy identifies a cache replacement policy function that implemented in another package.

const (
	// IDLE cache replacement policy.
	IDLE ReplacementPolicy = iota + 1
	// FIFO cache replacement policy.
	FIFO
	// LIFO cache replacement policy.
	LIFO
	// LRU cache replacement policy.
	LRU
	// LFU cache replacement policy.
	LFU
	// MRU cache replacement policy.
	MRU
	// ARC cache replacement policy.
	ARC
)

func (ReplacementPolicy) Available

func (c ReplacementPolicy) Available() bool

Available reports whether the given cache replacement policy is linked into the binary.

func (ReplacementPolicy) New

func (c ReplacementPolicy) New(cap int) Cache

New returns a new thread safe cache. New panics if the cache replacement policy function is not linked into the binary.

func (ReplacementPolicy) NewUnsafe

func (c ReplacementPolicy) NewUnsafe(cap int) Cache

NewUnsafe returns a new non-thread safe cache. NewUnsafe panics if the cache replacement policy function is not linked into the binary.

func (ReplacementPolicy) Register

func (c ReplacementPolicy) Register(function func(cap int) Cache)

Register registers a function that returns a new cache instance, of the given cache replacement policy function. This is intended to be called from the init function, in packages that implement cache replacement policy function.

func (ReplacementPolicy) String

func (c ReplacementPolicy) String() string

String returns string describes the cache replacement policy function.