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 (Notify)
• 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

package main 
import (
	"fmt"
	"time"

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

func main() {
	cache := libcache.LRU.New(10)

	eventc := make(chan libcache.Event, 10)
	cache.Notify(eventc)
	defer cache.Ignore(eventc)

	go func() {
		for {
			e := <-eventc
			fmt.Printf("Operation %s on Key %v \n", e.Op, e.Key)
		}
	}()

	cache.Load(1)
	cache.Store(1, 1)
	cache.Peek(1)
	cache.Delete(1)
}

GC

package main 
import (
	"fmt"
	"time"

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

func main() {
	cache := libcache.LRU.New(10)

	eventc := make(chan libcache.Event, 10)
	cache.Notify(eventc)
	defer cache.Ignore(eventc)

	go func() {
		for {
			e := <-eventc
			fmt.Printf("Operation %s on Key %v \n", e.Op, e.Key)
		}
	}()

	ctx, cacnel := context.WithTimeout(context.Background(), time.Second*2)
	defer cacnel()

	cache.StoreWithTTL(1, 1, time.Second)

	// GC is a long running function, evict expired items from the cache on time.
	libcache.GC(ctx, cache)

	cache.StoreWithTTL(1, 1, time.Second)
	time.Sleep(time.Second)

	// Runs a garbage collection and blocks the caller until the garbage collection is complete
	cache.GC()
}

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

• Constants
• func GC(ctx context.Context, cache Cache)
• type Cache
• type Event
• type Op
• 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

Constants

const (
	Read   = internal.Read
	Write  = internal.Write
	Remove = internal.Remove
)

These are the generalized cache operations that can trigger a event.

Functions

func GC

func GC(ctx context.Context, cache Cache)

GC runs a garbage collection to evict expired items from the cache on time.

GC trace expired items based on read-write barrier, therefore it listen to cache write events and capture the result of calling the GC method on cache to trigger the garbage collection loop at the right point in time.

GC is a long running function, it returns when ctx done, therefore the caller must start it in its own goroutine.

Experimental

Notice: This func is EXPERIMENTAL and may be changed or removed in a later release.

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 it when an entry is purged from the cache.
	//
	// Deprecated: use Notify instead.
	RegisterOnEvicted(f func(key, value interface{}))
	// RegisterOnExpired registers a function,
	// to call it when an entry TTL elapsed.
	//
	// Deprecated: use Notify instead.
	RegisterOnExpired(f func(key, value interface{}))
	// Notify causes cache to relay events to ch.
	// If no operations are provided, all incoming operations will be relayed to ch.
	// Otherwise, just the provided operations will.
	Notify(ch chan<- Event, ops ...Op)
	// Ignore causes the provided operations to be ignored. Ignore undoes the effect
	// of any prior calls to Notify for the provided operations.
	// If no operations are provided, ch removed.
	Ignore(ch chan<- Event, ops ...Op)
	// GC runs a garbage collection and blocks the caller until the
	// all expired items from the cache evicted.
	//
	// GC returns the remaining time duration for the next gc cycle
	// if there any, Otherwise, it return 0.
	//
	// Calling GC without waits for the duration to elapsed considered a no-op.
	GC() time.Duration
}

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

type Event

type Event = internal.Event

Event represents a single cache entry change.

type Op

type Op = internal.Op

Op describes a set of cache operations.

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.