icache

README

icache

icache is a no-dependency, generic support cache library for Go with high concurrent access performance. icache doean't require serialization, so the benchmark report you see at the bottom of the page is what you get at the end, there is no need to marshal and unmarshal anything and waste your valuable resources.

Features

• Thread safe: icache stores the data in multiple shards and uses a separate mutex for each shard.
• Generics: Using generics makes it type-safe.
• Tags: icache supports tags for entries and entries with the shared tags can be dropped at the same time.
• Pointer friendly: icache stores data as is. any object can be stored in icache, even pointers.
• TTL: ttl can be set to any thing from 1 seconds to infinity.

Installation

icache v2 requires go v1.8.0 and above.

go get github.com/mdaliyan/icache/v2

previous version for Go < 1.18

icache v1 is compatible with Go < 1.18, and it also doean't require serialization. it uses reflections to make sure about your data type.

Follow instructions at version v1.x.x for installation and usage. V1 will be maintained separately.

Usage

// make a new Pot:
// - to store user structs 
// - with expiration time of 1 Hour
var pot = icache.NewPot[user](
          icache.WithTTL(time.Hour),
    )

var User = user{
    ID:   "foo",
    Name: "John Doe",
    Age:  30,
}

// set user to "foo" key
pot.Set("foo", User)

// get the user previously set to "foo" key into user1 
user1, err := pot.Get("foo")

// you also can add tags to your entries
pot.Set("foo", User, "tag1", "tag2")
pot.Set("faa", User, "tag1")
pot.Set("fom", User, "tag3")

// and delete multiple entries at once
pot.DropTags("tag1")

Invalidation Strategies

• By Key
• By Tag
• By TTL: Using the WithTTL() option.

Benchmarks

goos: darwin
goarch: amd64
pkg: github.com/mdaliyan/icache/v2
cpu: Intel(R) Core(TM) i7-8557U CPU @ 1.70GHz
BenchmarkICache
BenchmarkICache-8             	9570999	    118.1 ns/op	   0 B/op	  0 allocs/op
BenchmarkICacheConcurrent
BenchmarkICacheConcurrent-8   	6117471	    191.4 ns/op	   0 B/op	  0 allocs/op

Plans for later

• Different invalidation Strategies can be added if it's needed.
• Maybe Remote sync

Documentation

Index

• Variables
• type Option
  • func WithTTL(duration time.Duration) Option
• type Pot
  • func NewPot[T any](options ...Option) Pot[T]

Variables

var ErrNotClosable = errors.New("pot cannot be closed")

ErrNotClosable means the pot doesn't have invalidation strategy.

var ErrNotFound = errors.New("entry not found")

ErrNotFound means the pot couldn't find the entry with the given key

Types

type Option

type Option func(pot customizablePot)

Option is the modifier function for the pot. icache uses options pattern.

func WithTTL

func WithTTL(duration time.Duration) Option

WithTTL sets the global ttl invalidation strategy for the pot. after setting an entry, it will be removed after the given duration time.

type Pot

type Pot[T any] interface {

	// Purge invalidates all entries
	Purge()

	// Len returns count of the entries
	Len() (l int)

	// Drop invalidates the entry with the given key
	Drop(key ...string)

	// DropTags invalidates all entries with the given tags
	DropTags(tags ...string)

	// Exists checks if the entry with the given key exists
	Exists(key string) bool

	// Set stores the variable in the given key entry
	// tags can be set or ignored
	Set(k string, v T, tags ...string)

	// Get restores the T previously stored as the given key
	// returns ErrNotFound if the key doesn't exist.
	Get(key string) (v T, err error)

	// ExpireTime returns expire time of the given entry
	ExpireTime(key string) (t *time.Time, err error)

	// Close stops the invalidation functionality goroutines.
	// - After closing, the pot resets and next entries you add won't expire. so don't use the pot after closing it.
	// - Pots without invalidation strategy cannot be closed.
	// - Panics if the pot is already closed.
	Close() error
}

Pot holds your cached data

func NewPot

func NewPot[T any](options ...Option) Pot[T]

NewPot creates new cache Pot with the given options.