cachita

README

Cachita

Cachita is a golang file, memory, SQL, Redis cache library

• Simple caching with auto type assertion included.
• In memory file cache index to avoid unneeded I/O.
• Msgpack based binary serialization using msgpack library for file caching.
• radix Redis client.
• Tag cache and invalidate cache keys based on tags, check in the examples.

API docs: https://pkg.go.dev/github.com/gadelkareem/cachita.

Examples: examples.

Installation

Install:

go get -u github.com/gadelkareem/cachita

Quickstart

func ExampleCache() {
	cache := cachita.Memory()
	err := cache.Put("cache_key", "some data", 1*time.Minute)
	if err != nil {
		panic(err)
	}

	if cache.Exists("cache_key") {
		// do something
	}

	var holder string
	err = cache.Get("cache_key", &holder)
	if err != nil && err != cachita.ErrNotFound {
		panic(err)
	}

	fmt.Printf("%s", holder) // prints "some data"

	err = cache.Invalidate("cache_key")
	if err != nil {
		panic(err)
	}

	// Output: some data

}

Benchmark

> go test -v -bench=. -benchmem
BenchmarkFileCacheWithInt
BenchmarkFileCacheWithInt-8              	    8966	    137991 ns/op	    2400 B/op	      37 allocs/op
BenchmarkFileCacheWithString
BenchmarkFileCacheWithString-8           	    8258	    153027 ns/op	    2417 B/op	      38 allocs/op
BenchmarkFileCacheWithMapInterface
BenchmarkFileCacheWithMapInterface-8     	    6908	    157232 ns/op	    4238 B/op	      60 allocs/op
BenchmarkFileCacheWithStruct
BenchmarkFileCacheWithStruct-8           	    7179	    165023 ns/op	    4992 B/op	      65 allocs/op
BenchmarkFile_Incr
BenchmarkFile_Incr-8                     	    4814	    279499 ns/op	    3004 B/op	      47 allocs/op
BenchmarkFile_Tag
BenchmarkFile_Tag-8                      	    3506	    324306 ns/op	    3028 B/op	      71 allocs/op
BenchmarkMemoryCacheWithInt
BenchmarkMemoryCacheWithInt-8            	  954620	      1340 ns/op	     112 B/op	       6 allocs/op
BenchmarkMemoryCacheWithString
BenchmarkMemoryCacheWithString-8         	  774190	      1333 ns/op	     128 B/op	       6 allocs/op
BenchmarkMemoryCacheWithMapInterface
BenchmarkMemoryCacheWithMapInterface-8   	  614234	      1850 ns/op	     520 B/op	      10 allocs/op
BenchmarkMemoryCacheWithStruct
BenchmarkMemoryCacheWithStruct-8         	  629415	      2244 ns/op	     664 B/op	      11 allocs/op
BenchmarkMemory_Incr
BenchmarkMemory_Incr-8                   	  527721	      2201 ns/op	      96 B/op	       4 allocs/op
BenchmarkMemory_Tag
BenchmarkMemory_Tag-8                    	  197188	      5393 ns/op	     598 B/op	      24 allocs/op
BenchmarkRedisCacheWithInt
BenchmarkRedisCacheWithInt-8             	    1591	    644581 ns/op	     460 B/op	      21 allocs/op
BenchmarkRedisCacheWithString
BenchmarkRedisCacheWithString-8          	    1770	    805753 ns/op	     945 B/op	      32 allocs/op
BenchmarkRedisCacheWithMapInterface
BenchmarkRedisCacheWithMapInterface-8    	    2138	    472726 ns/op	    2988 B/op	      54 allocs/op
BenchmarkRedisCacheWithStruct
BenchmarkRedisCacheWithStruct-8          	    2751	    475874 ns/op	    3876 B/op	      59 allocs/op
BenchmarkRedis_Incr
BenchmarkRedis_Incr-8                    	    1486	    826275 ns/op	    1201 B/op	      32 allocs/op
BenchmarkRedis_Tag
BenchmarkRedis_Tag-8                     	     660	   1822219 ns/op	    3309 B/op	     122 allocs/op
BenchmarkSqlCacheWithInt
BenchmarkSqlCacheWithInt-8               	     288	   4125553 ns/op	    4530 B/op	     111 allocs/op
BenchmarkSqlCacheWithString
BenchmarkSqlCacheWithString-8            	     302	   3839348 ns/op	    4373 B/op	     101 allocs/op
BenchmarkSqlCacheWithMapInterface
BenchmarkSqlCacheWithMapInterface-8      	     271	   4057435 ns/op	   10359 B/op	     339 allocs/op
BenchmarkSqlCacheWithStruct
BenchmarkSqlCacheWithStruct-8            	     286	   4106997 ns/op	   13065 B/op	     417 allocs/op
BenchmarkSql_Incr
BenchmarkSql_Incr-8                      	     219	   5618603 ns/op	    5771 B/op	     145 allocs/op
BenchmarkSql_Tag
BenchmarkSql_Tag-8                       	      91	  13543030 ns/op	   14772 B/op	     354 allocs/op
PASS
ok  	github.com/gadelkareem/cachita	40.686s

How to

Please go through examples to get an idea how to use this package.

See also

• Golang Helpers

Documentation

Index

• Constants
• Variables
• func Id(params ...string) string
• func IsErrorOk(err error) bool
• func TypeAssert(source, target interface{}) (err error)
• type Cache
  • func File() (Cache, error)
  • func Memory() Cache
  • func NewFileCache(dir string, ttl, tickerTtl time.Duration) (Cache, error)
  • func NewMemoryCache(ttl, tickerTtl time.Duration) Cache
  • func NewRedisCache(ttl time.Duration, poolSize int, prefix, addr string) (Cache, error)
  • func NewSqlCache(ttl, tickerTtl time.Duration, sql *sql.DB, tableName string, ...) (Cache, error)
  • func Redis(addr string) (Cache, error)
  • func Sql(driverName, dataSourceName string) (Cache, error)

Examples

• Cache
• File
• Memory
• NewMemoryCache

Constants

const FileIndex = "github.com/gadelkareem/cachita/file-index"

Variables

var (
	ErrNotFound = errors.New("cachita: cache not found")
	ErrExpired  = errors.New("cachita: cache expired")
)

Functions

func Id

func Id(params ...string) string

func IsErrorOk

func IsErrorOk(err error) bool

func TypeAssert

func TypeAssert(source, target interface{}) (err error)

Types

type Cache

type Cache interface {
	Get(key string, i interface{}) error
	Put(key string, i interface{}, ttl time.Duration) error // ttl 0:default ttl, -1: keep forever
	Incr(key string, ttl time.Duration) (int64, error)
	Tag(key string, tags ...string) error
	Exists(key string) bool
	Invalidate(key string) error
	InvalidateMulti(keys ...string) error
	InvalidateTags(tags ...string) error
}

Example

package main

import (
	"fmt"

	"time"

	"github.com/gadelkareem/cachita"
)

func main() {
	cache := cachita.Memory()
	err := cache.Put("cache_key", "some data", 1*time.Minute)
	if err != nil {
		panic(err)
	}

	if cache.Exists("cache_key") {
		// do something
	}

	var holder string
	err = cache.Get("cache_key", &holder)
	if err != nil && err != cachita.ErrNotFound {
		panic(err)
	}

	fmt.Printf("%s", holder) // prints "some data"

	err = cache.Invalidate("cache_key")
	if err != nil {
		panic(err)
	}

}

Output:

some data

func File

func File() (Cache, error)

Example

package main

import (
	"fmt"

	"time"

	"github.com/gadelkareem/cachita"
)

func main() {
	cache, err := cachita.File()
	if err != nil {
		panic(err)
	}

	err = cache.Put("cache_key", "some data", 1*time.Minute)
	if err != nil {
		panic(err)
	}

	var holder string
	err = cache.Get("cache_key", &holder)
	if err != nil && err != cachita.ErrNotFound {
		panic(err)
	}

	fmt.Printf("%s", holder) // prints "some data"

}

Output:

some data

func Memory

func Memory() Cache

Example

package main

import (
	"fmt"
	"net/url"

	"github.com/gadelkareem/cachita"
)

func main() {
	var u url.URL
	cacheId := cachita.Id(u.Scheme, u.Host, u.RequestURI())
	obj := make(map[string]interface{})
	obj["test"] = "data"
	err := cachita.Memory().Put(cacheId, obj, 0)
	if err != nil {
		panic(err)
	}

	var cacheObj map[string]interface{}
	err = cachita.Memory().Get(cacheId, &cacheObj)
	if err != nil && err != cachita.ErrNotFound && err != cachita.ErrExpired {
		panic(err)
	}
	fmt.Printf("%+v", cacheObj)

}

Output:

map[test:data]

func NewFileCache

func NewFileCache(dir string, ttl, tickerTtl time.Duration) (Cache, error)

func NewMemoryCache

func NewMemoryCache(ttl, tickerTtl time.Duration) Cache

Example

package main

import (
	"fmt"

	"time"

	"github.com/gadelkareem/cachita"
)

func main() {
	cache := cachita.NewMemoryCache(1*time.Millisecond, 1*time.Minute) // default ttl 1 millisecond

	err := cache.Put("cache_key", "some data", 0) // ttl = 0 means use default
	if err != nil {
		panic(err)
	}

	time.Sleep(2 * time.Millisecond)
	fmt.Printf("%t", cache.Exists("cache_key"))

}

Output:

false

func NewRedisCache

func NewRedisCache(ttl time.Duration, poolSize int, prefix, addr string) (Cache, error)

func NewSqlCache

func NewSqlCache(ttl, tickerTtl time.Duration, sql *sql.DB, tableName string, isPostgres ...bool) (Cache, error)

func Redis

func Redis(addr string) (Cache, error)

func Sql

func Sql(driverName, dataSourceName string) (Cache, error)