A pure non-intrusive cache library implemented by golang, you can use it to implement your own distributed cache

- [gdcache](#gdcache)
    - [Features](#features)
    - [Core principle](#core-principle)
    - [Save memory](#save-memory)
    - [Installation](#installation)
    - [Quick Start](#quick-start)
        - [Gorm usage](#gorm-usage)
        - [Xorm usage](#xorm-usage)
        - [Native SQL usage](#native-sql-usage)
    - [How to use](#how-to-use)
    - [Contributing](#contributing)
    - [License](#license)



# gdcache

gdcache is a pure non-intrusive cache library implemented by golang, you can use it to implement your own
cache. [中文文档](https://github.com/ulovecode/gdcache/blob/main/README_CN.md)

[![Go Report Card](https://goreportcard.com/badge/github.com/ulovecode/gdcache)](https://goreportcard.com/report/github.com/ulovecode/gdcache)
[![PkgGoDev](https://pkg.go.dev/badge/github.com/ulovecode/gdcache)](https://pkg.go.dev/github.com/ulovecode/gdcache)
[![codecov](https://codecov.io/gh/ulovecode/gdcache/branch/main/graph/badge.svg?token=4GNQINA6QX)](https://codecov.io/gh/ulovecode/gdcache)

## Features

- Automatically cache sql
- Reuse id cache
- Adapt to Xorm and Gorm framework
- Support cache joint key
- Lightweight
- Non-invasive
- High performance
- Flexible

## Core principle

The core principle of gdcache is to convert sql into id and cache it, and cache the entity corresponding to id. In this
way, each sql has the same id and can reuse the corresponding entity content.

![img.png](doc/flow-img.png)

As shown in the figure above, each piece of sql can be converted to the corresponding sql, and the bottom layer will
reuse these ids. If these ids are not queried, because we don’t know whether they are out of date or because these
values do not exist in the database, we will all be in the database and access these entities that cannot be retrieved
from the cache from the database. Get it once, and if it can get it, it will cache it once.

## Save memory

The conventional caching framework will cache the content of the result, but the gdcache cache library is different from
it. It will only cache the id of the result and find the value through the id. The advantage of this is that the value
can be reused, and the value corresponding to id will only be cached once.

## Installation

```shell
go get github.com/ulovecode/gdcache
```

## Quick Start

- The class to be cached must implement the `TableName()` method, and use `cache:"id"` to indicate the cached key. The
  default is to cache by `id`, and the value of the `cache` tag corresponds to Fields in the database, usually can be
  ignored.

```go
type User struct {
    Id   uint64 `cache:"id"` // Or omit the tag
    Name string
    Age  int
}

func (u User) TableName() string {
    return "user"
}
```

- If you want to use a joint key, you can add a `cache` tag to multiple fields

```go
type PublicRelations struct {
    RelatedId uint64 `cache:"related_id"`
    RelatedType string
    SourceId uint64 `cache:"source_id"`
    SourceType string
}

func (u PublicRelations) TableName() string {
    return "public_relations"
}
```

- Implement the `ICache` interface, you can use redis or gocache as the underlying implementation.

```go
type MemoryCacheHandler struct {
    data map[string][]byte
}

func (m MemoryCacheHandler) StoreAll(keyValues ...gdcache.KeyValue) (err error) {
    for _, keyValue := range keyValues {
        m.data[keyValue.Key] = keyValue.Value
    }
    return nil
}

func (m MemoryCacheHandler) Get(key string) (data []byte, has bool, err error) {
    bytes, has := m.data[key]
    return bytes, has, nil
}

func (m MemoryCacheHandler) GetAll(keys schemas.PK) (data []gdcache.ReturnKeyValue, err error) {
    returnKeyValues := make([]gdcache.ReturnKeyValue, 0)
    for _, key := range keys {
        bytes, has := m.data[key]
        returnKeyValues = append(returnKeyValues, gdcache.ReturnKeyValue{
        KeyValue: gdcache.KeyValue{
        Key:   key,
        Value: bytes,
    },
        Has: has,
    })
}
    return returnKeyValues, nil
}

func (m MemoryCacheHandler) DeleteAll(keys schemas.PK) error {
    for _, k := range keys {
        delete(m.data, k)
    }
    return nil
}

func NewMemoryCacheHandler() *MemoryCacheHandler {
    return &MemoryCacheHandler{
    data: make(map[string][]byte, 0),
    }
}
```

### Gorm usage

Implement the `IDB` interface

```go
type GormDB struct {
    db *gorm.DB
}

func (g GormDB) GetEntries(entries interface{}, sql string) error {
    tx := g.db.Raw(sql).Find(entries)
    return tx.Error
}

func (g GormDB) GetEntry(entry interface{}, sql string) (bool, error) {
    tx := g.db.Raw(sql).Take(entry)
    if gorm.ErrRecordNotFound == tx.Error {
        return false, nil
    }
    return tx.Error != gorm.ErrRecordNotFound, tx.Error
}

func NewGormCacheHandler() *gdcache.CacheHandler {
    return gdcache.NewCacheHandler(NewMemoryCacheHandler(), NewGormDd())
}

func NewGormDd() gdcache.IDB {
    db, err := gorm.Open(mysql.Open("root:root@tcp(127.0.0.1:3306)/test?charset=utf8&parseTime=True&loc=Local"), &gorm.Config{})
    if err != nil {
        panic(err)
    }
    return GormDB{
        db: db,
    }
}
```

### Xorm usage

Implement the `IDB` interface

```go
type XormDB struct {
    db *xorm.Engine
}

func (g XormDB) GetEntries(entries interface{}, sql string) ( error) {
    err := g.db.SQL(sql).Find(entries)
    return err
}

func (g XormDB) GetEntry(entry interface{}, sql string) ( bool, error) {
    has, err := g.db.SQL(sql).Get(entry)
    return has, err
}

func NewXormCacheHandler() *gdcache.CacheHandler {
    return gdcache.NewCacheHandler(NewMemoryCacheHandler(), NewXormDd())
}

func NewXormDd() gdcache.IDB {
    db, err := xorm.NewEngine("mysql", "root:root@/test?charset=utf8")
    if err != nil {
        panic(err)
    }
    return XormDB{
        db: db,
    }
}
```

### Native SQL usage

Implement the `IDB` interface

```go
type MemoryDb struct {
}

func NewMemoryDb() *MemoryDb {
    return &MemoryDb{}
}

func (m MemoryDb) GetEntries(entries interface{}, sql string) error {
    mockEntries := make([]MockEntry, 0)
    mockEntries = append(mockEntries, MockEntry{
    RelateId:   1,
    SourceId:   2,
    PropertyId: 3,
    })
    marshal, _ := json.Marshal(mockEntries)
    json.Unmarshal(marshal, entries)
    return nil
}

func (m MemoryDb) GetEntry(entry interface{}, sql string) (bool, error) {
    mockEntry := &MockEntry{
    RelateId:   1,
    SourceId:   2,
    PropertyId: 3,
    }
    marshal, _ := json.Marshal(mockEntry)
    json.Unmarshal(marshal, entry)
    return true, nil
}

func NewMemoryCache() *gdcache.CacheHandler {
    return gdcache.NewCacheHandler(NewMemoryCacheHandler(), NewMemoryDb())
}
```

## How to use

When querying a single entity, query through the entity's id and fill it into the entity. When getting multiple
entities, you can use any sql query and finally fill it into the entity. Both methods must be introduced into the body's
pointer.

```go
func TestNewGormCache(t *testing.T) {

    handler := NewGormCacheHandler()

    user := User{
        Id: 1,
    }
    has, err := handler.GetEntry(&user)
    if err != nil {
        t.FailNow()
    }
    if has {
        t.Logf("%v", user)
    }
    
    users := make([]User, 0)
    err = handler.GetEntries(&users, "SELECT * FROM user WHERE name = '33'")
    if err != nil {
        t.FailNow()
    }
    for _, user := range users {
        t.Logf("%v", user)
    }
    
    err = handler.GetEntries(&users, "SELECT * FROM user WHERE id in (3)")
    if err != nil {
        t.FailNow()
    }
    for _, user := range users {
        t.Logf("%v", user)
    }
    
    count, err = handler.GetEntriesAndCount(&users1, "SELECT * FROM user WHERE id in (1,2)")
    if err != nil {
        t.FailNow()
    }
    for _, user := range users1 {
        t.Logf("%v", user)
    }
    t.Log(count)
    }
    users3 := make([]User, 0)
    ids := make([]uint64, 0)
    count, err = handler.GetEntriesAndCount(&users3, "SELECT * FROM user WHERE id in ?", ids)
    if err != nil {
        t.FailNow()
    }
    for _, user := range users1 {
        t.Logf("%v", user)
    }
    t.Log(count)
    
    
    count, err = handler.GetEntriesAndCount(&users1, "SELECT * FROM user WHERE id =  ?", 1)
    if err != nil {
        t.FailNow()
    }
    for _, user := range users1 {
        t.Logf("%v", user)
    }
    t.Log(count)
    
    condition := []User{{Id:   1,},{Id:   2,},{Id:   3,}}
    
    err = handler.GetEntriesByIds(&users1, condition)
    if err != nil {
        t.FailNow()
    }
    for _, user := range users1 {
        t.Logf("%v", user)
    }
    t.Log(count)
```

Support placeholder `?`, replacement arrays and basic types

## Contributing

You can help provide better _gdcahe_ by submitting pr.

## License

© Jovanzhu, 2021~time.Now

Released under the  [MIT License](https://github.com/ulovecode/gdcache/blob/main/LICENSE)

gdcache

A flexible multi-layer Go caching library to deal with in-memory and shared cache by adopting Cache-Aside pattern

# go-cache

[![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/github.com/viney-shih/go-cache?tab=doc)
[![Build Status](https://app.travis-ci.com/viney-shih/go-cache.svg?branch=master)](https://app.travis-ci.com/viney-shih/go-cache)
[![Go Report Card](https://goreportcard.com/badge/github.com/viney-shih/go-cache)](https://goreportcard.com/report/github.com/viney-shih/go-cache)
[![codecov](https://codecov.io/gh/viney-shih/go-cache/branch/master/graph/badge.svg?token=QKRiNSU5Gn)](https://codecov.io/gh/viney-shih/go-cache)
[![Coverage Status](https://coveralls.io/repos/github/viney-shih/go-cache/badge.svg?branch=master)](https://coveralls.io/github/viney-shih/go-cache?branch=master)
[![Maintainability](https://api.codeclimate.com/v1/badges/5b70576957b8af88de6e/maintainability)](https://codeclimate.com/github/viney-shih/go-cache/maintainability)
[![Sourcegraph](https://sourcegraph.com/github.com/viney-shih/go-cache/-/badge.svg)](https://sourcegraph.com/github.com/viney-shih/go-cache?badge)
[![License](http://img.shields.io/badge/License-Apache_2-red.svg?style=flat)](http://www.apache.org/licenses/LICENSE-2.0)
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fviney-shih%2Fgo-cache.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fviney-shih%2Fgo-cache?ref=badge_shield)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go#caches)

<p align="center">
  <img src="assets/logo.png" title="viney-shih/go-cache" />
  <span style="font-size: 14px; font-weight: 400; color: rgba(117, 117, 117, 1); font-family: sohne, "Helvetica Neue", Helvetica, Arial, sans-serif;">Photo by <a href="https://github.com/ashleymcnamara">Ashley McNamara</a>, via <a href="https://github.com/ashleymcnamara/gophers">ashleymcnamara/gophers</a> (CC BY-NC-SA 4.0)</span>
</p>

A flexible multi-layered caching library interacts with **private (in-memory) cache** and **shared cache** (i.e. Redis) in Go. It provides `Cache-Aside` strategy when dealing with both, and maintains the consistency of private cache between distributed systems by `Pub-Sub` pattern.

Caching is a common technique that aims to improve the performance and scalability of a system. It does this by temporarily copying frequently accessed data to fast storage close to the application. Distributed applications typically implement either or both of the following strategies when caching data:
- Using a **private cache**, where data is held locally on the computer that's running an instance of an application or service.
- Using a **shared cache**, serving as a common source that can be accessed by multiple processes and machines.

![Using a local private cache with a shared cache](./doc/img/caching.png)
Ref: [https://docs.microsoft.com/en-us/azure/architecture/best-practices/images/caching/caching3.png](https://docs.microsoft.com/en-us/azure/architecture/best-practices/images/caching/caching3.png "Using a local private cache with a shared cache")

Considering the flexibility, efficiency and consistency, we starts to build up our own framework.

## Features
- **Easy to use** : provide a friendly interface to deal with both caching mechnaism by simple configuration. Limit the size of memory on single instance (pod) as well.
- **Maintain consistency** : evict keys between distributed systems by `Pub-Sub` pattern.  
- **Data compression** : provide customized marshal and unmarshal functions.
- **Fix concurrency issue** : prevent data racing happened on single instance (pod).
- **Metric** : provide callback functions to measure the performance. (i.e. hit rate, private cache usage, ...)

## Data flow
### Load the cache with `Cache-Aside` strategy
```mermaid
sequenceDiagram
    participant APP as Application
    participant M as go-cache
    participant L as Local Cache
    participant S as Shared Cache
    participant R as Resource (Microservice / DB)
    
    APP ->> M: Cache.Get() / Cache.MGet()
    alt Local Cache hit
        M ->> L: Adapter.MGet()
        L -->> M: {[]Value, error}
        M -->> APP: return
    else Local Cache miss but Shared Cache hit
        M ->> L: Adapter.MGet()
        L -->> M: cache miss
        M ->> S: Adapter.MGet()
        S -->> M: {[]Value, error}
        M ->> L: Adapter.MSet()
        M -->> APP: return
    else All miss
        M ->> L: Adapter.MGet()
        L -->> M: cache miss
        M ->> S: Adapter.MGet()
        S -->> M: cache miss
        M ->> R: OneTimeGetterFunc() / MGetterFunc()
        R -->> M: return from getter
        M ->> S: Adapter.MSet()
        M ->> L: Adapter.MSet()
        M -->> APP: return
    end

```

### Evict the cache
```mermaid
sequenceDiagram
    participant APP as Application
    participant M as go-cache
    participant L as Local Cache
    participant S as Shared Cache
    participant PS as PubSub
    
    APP ->> M: Cache.Del()
    M ->> S: Adapter.Del()
    S -->> M: return error if necessary
    M ->> L: Adapter.Del()
    L -->> M: return error if necessary
    M ->> PS: Pubsub.Pub() (broadcast key eviction)
    M -->> APP: return nil or error
```

## Installation
```sh
go get github.com/viney-shih/go-cache
```

## Get Started
### Basic usage: Set-And-Get

By adopting `Singleton` pattern, initialize the *Factory* in main.go at the beginning, and deliver it to each package or business logic.

```go
// Initialize the Factory in main.go
tinyLfu := cache.NewTinyLFU(10000)
rds := cache.NewRedis(redis.NewRing(&redis.RingOptions{
    Addrs: map[string]string{
        "server1": ":6379",
    },
}))

cacheFactory := cache.NewFactory(rds, tinyLfu)
```

Treat it as a common **key:value** store like Redis. But more advanced, it coordinated the usage between multi-layered caching mechanism inside.

```go
type Object struct {
    Str string
    Num int
}

func Example_setAndGetPattern() {
    // We create a group of cache named "set-and-get".
    // It uses the shared cache only. Each key will be expired within ten seconds.
    c := cacheFactory.NewCache([]cache.Setting{
        {
            Prefix: "set-and-get",
            CacheAttributes: map[cache.Type]cache.Attribute{
                cache.SharedCacheType: {TTL: 10 * time.Second},
            },
        },
    })

    ctx := context.TODO()

    // set the cache
    obj := &Object{
        Str: "value1",
        Num: 1,
    }
    if err := c.Set(ctx, "set-and-get", "key", obj); err != nil {
        panic("not expected")
    }

    // read the cache
    container := &Object{}
    if err := c.Get(ctx, "set-and-get", "key", container); err != nil {
        panic("not expected")
    }
    fmt.Println(container) // Output: Object{ Str: "value1", Num: 1}

    // read the cache but failed
    if err := c.Get(ctx, "set-and-get", "no-such-key", container); err != nil {
        fmt.Println(err) //  Output: errors.New("cache key is missing")
    }

    // Output:
    // &{value1 1}
    // cache key is missing
}

```

### Advanced usage: `Cache-Aside` strategy

`GetByFunc()` is the easier way to deal with the cache by implementing the **getter function** in the parameter. When the cache is missing, it is going to refill the cache automatically.

```go
func ExampleCache_GetByFunc() {
    // We create a group of cache named "get-by-func".
    // It uses the local cache only with TTL of ten minutes.
    c := cacheFactory.NewCache([]cache.Setting{
        {
            Prefix: "get-by-func",
            CacheAttributes: map[cache.Type]cache.Attribute{
                cache.LocalCacheType: {TTL: 10 * time.Minute},
            },
            MarshalFunc:   msgpack.Marshal, // msgpack is from "github.com/vmihailenco/msgpack/v5"
            UnmarshalFunc: msgpack.Unmarshal,
        },
    })

    ctx := context.TODO()
    container2 := &Object{}
    if err := c.GetByFunc(ctx, "get-by-func", "key2", container2, func() (interface{}, error) {
        // The getter is used to generate data when cache missed, and refill the cache automatically..
        // You can read from DB or other microservices.
        // Assume we read from MySQL according to the key "key2" and get the value of Object{Str: "value2", Num: 2}
        return Object{Str: "value2", Num: 2}, nil
    }); err != nil {
        panic("not expected")
    }

    fmt.Println(container2) // Object{ Str: "value2", Num: 2}

    // Output:
    // &{value2 2}
}
```

`MGetter` is another approaching way to do this. Set this function durning registering the *Setting*.

```go
func ExampleService_Create_mGetter() {
    // We create a group of cache named "mgetter".
    // It uses both shared and local caches with separated TTL of one hour and ten minutes.
    c := cacheFactory.NewCache([]cache.Setting{
        {
            Prefix: "mgetter",
            CacheAttributes: map[cache.Type]cache.Attribute{
                cache.SharedCacheType: {TTL: time.Hour},
                cache.LocalCacheType:  {TTL: 10 * time.Minute},
            },
            MGetter: func(keys ...string) (interface{}, error) {
                // The MGetter is used to generate data when cache missed, and refill the cache automatically..
                // You can read from DB or other microservices.
                // Assume we read from MySQL according to the key "key3" and get the value of Object{Str: "value3", Num: 3}
                // HINT: remember to return as a slice, and the item order needs to consist with the keys in the parameters.
                return []Object{{Str: "value3", Num: 3}}, nil
            },
            MarshalFunc:   cache.Marshal,
            UnmarshalFunc: cache.Unmarshal,
        },
    })

    ctx := context.TODO()
    container3 := &Object{}
    if err := c.Get(ctx, "mgetter", "key3", container3); err != nil {
        panic("not expected")
    }

    fmt.Println(container3) // Object{ Str: "value3", Num: 3}

    // Output:
    // &{value3 3}
}
```

[More examples](./example_advanced_test.go)

## References
- https://docs.microsoft.com/en-us/azure/architecture/best-practices/caching
- https://github.com/vmihailenco/go-cache-benchmark
- https://github.com/go-redis/cache

## License
[Apache-2.0](https://opensource.org/licenses/Apache-2.0)


[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fviney-shih%2Fgo-cache.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fviney-shih%2Fgo-cache?ref=badge_large)

go-cache

Eventually consistent distributed in-memory cache Go library

# bcache

[![godoc](https://godoc.org/github.com/iwanbk/bcache?status.svg)](http://godoc.org/github.com/iwanbk/bcache)
[![Build Status](https://travis-ci.org/iwanbk/bcache.svg?branch=master)](https://travis-ci.org/iwanbk/bcache)
[![codecov](https://codecov.io/gh/iwanbk/bcache/branch/master/graph/badge.svg)](https://codecov.io/gh/iwanbk/bcache)
[![Go Report Card](https://goreportcard.com/badge/github.com/iwanbk/bcache)](https://goreportcard.com/report/github.com/iwanbk/bcache)
[![Maintainability](https://api.codeclimate.com/v1/badges/0535095fdd215f2e22ad/maintainability)](https://codeclimate.com/github/iwanbk/bcache/maintainability)

A Go Library to create distributed in-memory cache inside your app.

## Features

- LRU cache with configurable maximum keys
- Eventual Consistency synchronization between peers
- Data are replicated to all nodes
- cache filling mechanism. When the cache of the given key is not exist, bcache coordinates cache fills such that only one call populates the cache to avoid thundering herd or [cache stampede](https://en.wikipedia.org/wiki/Cache_stampede)

## Why using it

- if extra network hops needed by external caches like `redis` or `memcached` is not acceptable for you
- you only need cache with simple `Set`, `Get`, and `Delete` operation
- you have enough RAM to hold the cache data

## How it Works

1. Nodes find each other using [Gossip Protocol](https://en.wikipedia.org/wiki/Gossip_protocol)

Only need to specify one or few nodes as bootstrap nodes, and all nodes will find each other using gossip protocol

2. When there is cache `Set` and `Delete`, the event will be propagated to all of the nodes.

So, all of the nodes will eventually have synced data.



## Cache filling

Cache filling mechanism is provided in [GetWithFiller](https://godoc.org/github.com/iwanbk/bcache#Bcache.GetWithFiller) func.

When the cache for the given key is not exists:
- it will call the provided `Filler`
- set the cache using value returned by the `Filler`

Even there are many goroutines which call `GetWithFiller`, the given `Filler` func
will only called once for each of the key.
Cache stampede could be avoided this way.

## Quick Start

In server 1
```go
bc, err := New(Config{
	// PeerID:     1, // leave it, will be set automatically based on mac addr
	ListenAddr: "192.168.0.1:12345",
	Peers:      nil, // it nil because we will use this node as bootstrap node
	MaxKeys:    1000,
	Logger:     logrus.New(),
})
if err != nil {
    log.Fatalf("failed to create cache: %v", err)
}
bc.Set("my_key", "my_val",86400)
```

In server 2
```go
bc, err := New(Config{
	// PeerID:     2, // leave it, will be set automatically based on mac addr
	ListenAddr: "192.168.0.2:12345",
	Peers:      []string{"192.168.0.1:12345"},
	MaxKeys:    1000,
	Logger:     logrus.New(),
})
if err != nil {
    log.Fatalf("failed to create cache: %v", err)
}
bc.Set("my_key2", "my_val2", 86400)
```

In server 3
```go
bc, err := New(Config{
	// PeerID:     3,// will be set automatically based on mac addr
	ListenAddr: "192.168.0.3:12345",
	Peers:      []string{"192.168.0.1:12345"},
	MaxKeys:    1000,
	Logger:     logrus.New(),
})
if err != nil {
    log.Fatalf("failed to create cache: %v", err)
}
val, exists := bc.Get("my_key2")
```

### GetWithFiller example

```go
c, err := New(Config{
	PeerID:     3,
	ListenAddr: "192.168.0.3:12345",
	Peers:      []string{"192.168.0.1:12345"},
	MaxKeys:    1000,
})
if err != nil {
    log.Fatalf("failed to create cache: %v", err)
}
val, exp,err  := bc.GetWithFiller("my_key2",func(key string) (string, error) {
        // get value from database
         .....
         //
		return value, 0, nil
}, 86400)
```

## Credits

- [weaveworks/mesh](https://github.com/weaveworks/mesh) for the gossip library
- [groupcache](https://github.com/golang/groupcache) for the inspiration

bcache

Efficient key/value cache for gigabytes of data

# BigCache [![Build Status](https://github.com/allegro/bigcache/workflows/build/badge.svg)](https://github.com/allegro/bigcache/actions?query=workflow%3Abuild)&nbsp;[![Coverage Status](https://coveralls.io/repos/github/allegro/bigcache/badge.svg?branch=main)](https://coveralls.io/github/allegro/bigcache?branch=main)&nbsp;[![GoDoc](https://godoc.org/github.com/allegro/bigcache/v3?status.svg)](https://godoc.org/github.com/allegro/bigcache/v3)&nbsp;[![Go Report Card](https://goreportcard.com/badge/github.com/allegro/bigcache/v3)](https://goreportcard.com/report/github.com/allegro/bigcache/v3)

Fast, concurrent, evicting in-memory cache written to keep big number of entries without impact on performance.
BigCache keeps entries on heap but omits GC for them. To achieve that, operations on byte slices take place,
therefore entries (de)serialization in front of the cache will be needed in most use cases.

Requires Go 1.12 or newer.

## Usage

### Simple initialization

```go
import (
	"context"
	"fmt"
	"time"
	"github.com/allegro/bigcache/v3"
)

cache, _ := bigcache.New(context.Background(), bigcache.DefaultConfig(10 * time.Minute))

cache.Set("my-unique-key", []byte("value"))

entry, _ := cache.Get("my-unique-key")
fmt.Println(string(entry))
```

### Custom initialization

When cache load can be predicted in advance then it is better to use custom initialization because additional memory
allocation can be avoided in that way.

```go
import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/allegro/bigcache/v3"
)

config := bigcache.Config {
		// number of shards (must be a power of 2)
		Shards: 1024,

		// time after which entry can be evicted
		LifeWindow: 10 * time.Minute,

		// Interval between removing expired entries (clean up).
		// If set to <= 0 then no action is performed.
		// Setting to < 1 second is counterproductive — bigcache has a one second resolution.
		CleanWindow: 5 * time.Minute,

		// rps * lifeWindow, used only in initial memory allocation
		MaxEntriesInWindow: 1000 * 10 * 60,

		// max entry size in bytes, used only in initial memory allocation
		MaxEntrySize: 500,

		// prints information about additional memory allocation
		Verbose: true,

		// cache will not allocate more memory than this limit, value in MB
		// if value is reached then the oldest entries can be overridden for the new ones
		// 0 value means no size limit
		HardMaxCacheSize: 8192,

		// callback fired when the oldest entry is removed because of its expiration time or no space left
		// for the new entry, or because delete was called. A bitmask representing the reason will be returned.
		// Default value is nil which means no callback and it prevents from unwrapping the oldest entry.
		OnRemove: nil,

		// OnRemoveWithReason is a callback fired when the oldest entry is removed because of its expiration time or no space left
		// for the new entry, or because delete was called. A constant representing the reason will be passed through.
		// Default value is nil which means no callback and it prevents from unwrapping the oldest entry.
		// Ignored if OnRemove is specified.
		OnRemoveWithReason: nil,
	}

cache, initErr := bigcache.New(context.Background(), config)
if initErr != nil {
	log.Fatal(initErr)
}

cache.Set("my-unique-key", []byte("value"))

if entry, err := cache.Get("my-unique-key"); err == nil {
	fmt.Println(string(entry))
}
```

### `LifeWindow` & `CleanWindow`

1. `LifeWindow` is a time. After that time, an entry can be called dead but not deleted.

2. `CleanWindow` is a time. After that time, all the dead entries will be deleted, but not the entries that still have life.

## [Benchmarks](https://github.com/allegro/bigcache-bench)

Three caches were compared: bigcache, [freecache](https://github.com/coocood/freecache) and map.
Benchmark tests were made using an
i7-6700K CPU @ 4.00GHz with 32GB of RAM on Ubuntu 18.04 LTS (5.2.12-050212-generic).

Benchmarks source code can be found [here](https://github.com/allegro/bigcache-bench)

### Writes and reads

```bash
go version
go version go1.13 linux/amd64

go test -bench=. -benchmem -benchtime=4s ./... -timeout 30m
goos: linux
goarch: amd64
pkg: github.com/allegro/bigcache/v3/caches_bench
BenchmarkMapSet-8                     	12999889	       376 ns/op	     199 B/op	       3 allocs/op
BenchmarkConcurrentMapSet-8           	 4355726	      1275 ns/op	     337 B/op	       8 allocs/op
BenchmarkFreeCacheSet-8               	11068976	       703 ns/op	     328 B/op	       2 allocs/op
BenchmarkBigCacheSet-8                	10183717	       478 ns/op	     304 B/op	       2 allocs/op
BenchmarkMapGet-8                     	16536015	       324 ns/op	      23 B/op	       1 allocs/op
BenchmarkConcurrentMapGet-8           	13165708	       401 ns/op	      24 B/op	       2 allocs/op
BenchmarkFreeCacheGet-8               	10137682	       690 ns/op	     136 B/op	       2 allocs/op
BenchmarkBigCacheGet-8                	11423854	       450 ns/op	     152 B/op	       4 allocs/op
BenchmarkBigCacheSetParallel-8        	34233472	       148 ns/op	     317 B/op	       3 allocs/op
BenchmarkFreeCacheSetParallel-8       	34222654	       268 ns/op	     350 B/op	       3 allocs/op
BenchmarkConcurrentMapSetParallel-8   	19635688	       240 ns/op	     200 B/op	       6 allocs/op
BenchmarkBigCacheGetParallel-8        	60547064	        86.1 ns/op	     152 B/op	       4 allocs/op
BenchmarkFreeCacheGetParallel-8       	50701280	       147 ns/op	     136 B/op	       3 allocs/op
BenchmarkConcurrentMapGetParallel-8   	27353288	       175 ns/op	      24 B/op	       2 allocs/op
PASS
ok  	github.com/allegro/bigcache/v3/caches_bench	256.257s
```

Writes and reads in bigcache are faster than in freecache.
Writes to map are the slowest.

### GC pause time

```bash
go version
go version go1.13 linux/amd64

go run caches_gc_overhead_comparison.go

Number of entries:  20000000
GC pause for bigcache:  1.506077ms
GC pause for freecache:  5.594416ms
GC pause for map:  9.347015ms
```

```
go version
go version go1.13 linux/arm64

go run caches_gc_overhead_comparison.go
Number of entries:  20000000
GC pause for bigcache:  22.382827ms
GC pause for freecache:  41.264651ms
GC pause for map:  72.236853ms
```

Test shows how long are the GC pauses for caches filled with 20mln of entries.
Bigcache and freecache have very similar GC pause time.

### Memory usage

You may encounter system memory reporting what appears to be an exponential increase, however this is expected behaviour. Go runtime allocates memory in chunks or 'spans' and will inform the OS when they are no longer required by changing their state to 'idle'. The 'spans' will remain part of the process resource usage until the OS needs to repurpose the address. Further reading available [here](https://utcc.utoronto.ca/~cks/space/blog/programming/GoNoMemoryFreeing).

## How it works

BigCache relies on optimization presented in 1.5 version of Go ([issue-9477](https://github.com/golang/go/issues/9477)).
This optimization states that if map without pointers in keys and values is used then GC will omit its content.
Therefore BigCache uses `map[uint64]uint32` where keys are hashed and values are offsets of entries.

Entries are kept in byte slices, to omit GC again.
Byte slices size can grow to gigabytes without impact on performance
because GC will only see single pointer to it.

### Collisions

BigCache does not handle collisions. When new item is inserted and it's hash collides with previously stored item, new item overwrites previously stored value.

## Bigcache vs Freecache

Both caches provide the same core features but they reduce GC overhead in different ways.
Bigcache relies on `map[uint64]uint32`, freecache implements its own mapping built on
slices to reduce number of pointers.

Results from benchmark tests are presented above.
One of the advantage of bigcache over freecache is that you don’t need to know
the size of the cache in advance, because when bigcache is full,
it can allocate additional memory for new entries instead of
overwriting existing ones as freecache does currently.
However hard max size in bigcache also can be set, check [HardMaxCacheSize](https://godoc.org/github.com/allegro/bigcache#Config).

## HTTP Server

This package also includes an easily deployable HTTP implementation of BigCache, which can be found in the [server](/server) package.

## More

Bigcache genesis is described in allegro.tech blog post: [writing a very fast cache service in Go](http://allegro.tech/2016/03/writing-fast-cache-service-in-go.html)

## License

BigCache is released under the Apache 2.0 license (see [LICENSE](LICENSE))


BigCache

BigCache with clustering support and individual item expiration

clusteredBigCache
=================

[![Go Report Card](https://goreportcard.com/badge/github.com/oastuff/clusteredBigCache)](https://goreportcard.com/report/github.com/oastuff/clusteredBigCache)

This is a library based on [bigcache](https://github.com/allegro/bigcache) with some modifications to support
* clustering and
* individual item expiration

Bigcache is an excellent piece of software but the fact that items could only expire based on a predefined 
value was not just too appealing. Bigcache had to be modified to support individual expiration of items using
a single timer. This happens by you specifying a time value as you add items to the cache.
Running two or more instances of an application that would require some level of caching would normally
default to memcache or redis which are external applications adding to the mix of services required for your
application to run.

With clusteredBigCache there is no requirement to run an external application to provide caching for multiple
instances of your application. The library handles caching as well as clustering the caches between multiple
instances of your application providing you with simple library APIs (by just calling functions) to store and
get your values.

With clusteredBigCache, when you store a value in one instance of your application and every other instance 
or any other application for that matter that you configure to form/join your "cluster" will
see that exact same value.

## Installing

### Using *go get*

    $ go get github.com/oaStuff/clusteredBigCache

## Samples 1

This is the application responsible for storing data into the cache

```go
package main

import (
    "fmt"
    "bufio"
    "os"
    "github.com/oaStuff/clusteredBigCache/Cluster"
    "strings"
    "time"
)

//
//main function
//
func main() {
    fmt.Println("starting...")
    cache := clusteredBigCache.New(clusteredBigCache.DefaultClusterConfig(), nil)
    count := 1
    cache.Start()

    reader := bufio.NewReader(os.Stdin)
    var data string
    for strings.ToLower(data) != "exit" {
        fmt.Print("enter data : ")
        data, _ = reader.ReadString('\n')
        data = strings.TrimSpace(data)
        err := cache.Put(fmt.Sprintf("key_%d", count), []byte(data), time.Minute * 60)
        if err != nil {
            panic(err)
       	}
       	fmt.Printf("'%s' stored under key 'key_%d'\n", data, count)
       	count++
   	}
}

```

##### Explanation:

The above application captures data from the keyboard and stores them inside clusteredBigCache
starting with keys 'key_1', 'key_2'...'key_n'. As the user types and presses the enter key the data is stored in
the cache.

`cache := clusteredBigCache.New(clusteredBigCache.DefaultClusterConfig(), nil)`
This statement will create the cache using the default configuration. This configuration has default 
values for *LocalPort = 9911*, *Join = false* amongst others. If you intend to use this library for applications
that will run on the same machine, you will have to give unique values for *LocalPort*

`cache.Start()` This **must** be called before using any other method on this cache.

`err := cache.Put(fmt.Sprintf("key_%d", count), []byte(data), time.Minute * 60)`. You set values in the cache
giving it a key, the data as a `[]byte` slice and the expiration or time to live (ttl) for that key/value within the cache.
When the key/value pair reaches its expiration time, they are removed automatically.


## Samples 2

This is the application responsible for reading data of the cache. This can be run on the same or different machine
on the network.

```go
package main

import (
    "github.com/oaStuff/clusteredBigCache/Cluster"
    "bufio"
    "os"
    "strings"
    "fmt"
    "time"
)

//
//
func main() {
    config := clusteredBigCache.DefaultClusterConfig()
    config.LocalPort = 8888
    config.Join = true
    config.JoinIp = "127.0.0.1:9911"
    cache := clusteredBigCache.New(config, nil)
    err := cache.Start()
    if err != nil {
        panic(err)
    }
    
    reader := bufio.NewReader(os.Stdin)
    var data string
    for strings.ToLower(data) != "exit" {
        fmt.Print("enter key : ")
        data, _ = reader.ReadString('\n')
        data = strings.TrimSpace(data)
        value, err := cache.Get(data, time.Millisecond * 160)
        if err != nil {
            fmt.Println(err)
            continue
        }
        fmt.Printf("you got '%s' from the cache\n", value)
    }
}

```

##### Explanation:

The above application reads a string from the keyboard which should represent a key for a value in clusteredBigCache.
If a user enters the corresponding keys shown in sample1 above ('key_1', 'key_2'...'key_n'), the corresponding values
will be returned.

```go
    config := clusteredBigCache.DefaultClusterConfig()
    config.LocalPort = 8888
    config.Join = true
    config.JoinIp = "127.0.0.1:9911"
    cache := clusteredBigCache.New(config, nil)
    err := cache.Start()
```

The above uses the default configuration to create a config and modifies what it actually needs.
`config.LocalPort = 8888` has to be changed since this application will run on the same machine with the sample1 
application. This is to avoid 'port already in use' errors. 

`config.Join = true`. For an application to join another
application or applications using clusteredBigCache, it **must** set *config.Join* value to *true* and set `config.JoinIP` to 
the IP address of one of the systems using clusteredBigCache eg `config.Join = "127.0.0.1:9911`. This example says that this application 
wants to join another application using clusteredBigCache at IP address *127.0.0.1* and port number *9911*.

`cache := clusteredBigCache.New(config, nil)` creates the cache and `cache.Start()` must be called to start everything running.

__**NB**__

After `cache.Start()` is called the library tries to connect to the specified IP address using the specified port. 
When successfully connected, it create a cluster of applications using clusteredBigCache as a single cache. ie all applications connected will see every value 
every application sets in the cache.

#### Sample way to parse config in an app

```go
    join := flag.String("join", "", "ipAddr:port number of remote server")
    localPort := flag.Int("port", 6060, "local server port to bind to")

    
    flag.Parse()
    
    config := clusteredBigCache.DefaultClusterConfig()
    if *join != "" {
        config.JoinIp = *join
        config.Join = true
    }
    config.LocalPort = *localPort
```

Your application could pass parameters to it in any form and make use of them in configuring clusteredBigCache. The
above sample just only catered for `join` and `localport`. If you want network connections between machine to be reconnected
in the event of a disconnection, you will have to set `config.ReconnectOnDisconnect = true`.

#### Logging within the library

clusteredBigCache takes a second parameter is its New() function for logging.
This function expects an interface of 
```go
type AppLogger interface {
    Info(msg string)
    Warn(msg string)
    Critical(msg string)
    Error(msg string)
}
```

You could easily just wrap any logger within a `struct` and provide this interface method for that struct and simple
delegate calls to the underlining logger or better still just wrap a logger function to provide the interface like example bellow

```go
type myLogger func(...interface{})

func (log myLogger) Info(msg string)  {
	log(msg)
}

func (log myLogger) Warn(msg string)  {
	log(msg)
}

func (log myLogger) Error(msg string)  {
	log(msg)
}

func (log myLogger) Critical(msg string)  {
	log(msg)
}


cache := clusteredBigCache.New(config, myLogger(log.Println))

```

### Using Passive client
Passive client are nodes in the clusteredBigCache network that do not store any data locally but functions all the same 
like every other node. To create a passive client you simply call `clusteredBigCache.NewPassiveClient("linux_box_100","localhost:9090", 8885, 0, 0, 0, nil)`
This will connect to an existing cluster at address *localhost:9090* and join the cluster. the *linux_box_100* is the node's id.
This can be an empty string if you want an auto generated id. Every other function can be performed
on the returned object.  

##### credits
Core cache system from [bigcache](https://github.com/allegro/bigcache)

Data structures from [emirpasic](https://github.com/emirpasic/gods)

### LICENSE
MIT.






clusteredBigCache

Full implementation of Oracle Coherence cache API for Go applications using gRPC as network transport

# Coherence Go Client

![Coherence Go Client](https://github.com/oracle/coherence-go-client/actions/workflows/build.yaml/badge.svg?branch=main)
[![License](http://img.shields.io/badge/license-UPL%201.0-blue.svg)](https://oss.oracle.com/licenses/upl/)
[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=oracle_coherence-go-client&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=oracle_coherence-go-client)

[![Go Report Card](https://goreportcard.com/badge/github.com/oracle/coherence-go-client)](https://goreportcard.com/report/github.com/oracle/coherence-go-client)
[![GitHub release (latest by date)](https://img.shields.io/github/v/release/oracle/coherence-go-client)](https://github.com/oracle/coherence-go-client/releases)
<a href="https://pkg.go.dev/github.com/oracle/coherence-go-client/v2/coherence"><img src="https://pkg.go.dev/badge/go get github.com/oracle/coherence-go-client.svg" alt="Go Reference"></a>

The Coherence Go Client allows Go applications to act as cache clients 
to a Coherence Cluster using gRPC for the network transport.

> [Coherence](https://coherence.community/) is a scalable, fault-tolerant, cloud-ready, distributed platform for building grid-based applications and reliably storing data. The product is used at scale, for both compute and raw storage, in a vast array of industries such as critical financial trading systems, high performance telecommunication products and eCommerce applications.

#### Features

* Familiar Map-like interface for manipulating cache entries including but not limited to:
  * `Put`, `PutWithExpiry`, `PutIfAbsent`, `PutAll`, `Get`, `GetAll`, `Remove`, `Clear`, `GetOrDefault`, `Replace`, `ReplaceMapping`, `Size`, `IsEmpty`, `ContainsKey`, `ContainsValue`, `ContainsEntry`
* Cluster-side querying, aggregation and filtering of map entries
* Cluster-side manipulation of map entries using EntryProcessors
* Registration of listeners to be notified of:
  * mutations such as insert, update and delete on Maps
  * map lifecycle events such as truncated, released or destroyed
  * session lifecycle events such as connected, disconnected, reconnected and closed 
* Support for storing Go structs as JSON as well as the ability to serialize to Java objects on the server for access from other Coherence language API's 
* Near cache support to cache frequently accessed data in the Go client to avoid sending requests across the network
* Support for simple and double-ended queues in Coherence Community Edition 25.03+ and commercial version 14.1.2.0+
* Full support for Go generics in all Coherence API's

#### Requirements

* Coherence CE 22.06.4+, 25.03+ or Coherence 14.1.1.2206.4+ Commercial edition with a configured [gRPCProxy](https://docs.oracle.com/en/middleware/standalone/coherence/14.1.1.2206/develop-remote-clients/using-coherence-grpc-server.html).
* Go 1.23.+

> Note: If you wish to use the queues API in the latest release, you must use CE 24.09 or commercial version 14.1.2.0.x.

> Note: If you wish to use Go versions < 1.23 you can use v2.0.0 of the client.

#### <a name="start"></a> Starting a gRPC enabled Coherence cluster

Before testing the Go client, you must ensure a Coherence cluster is available. 
For local development, we recommend using the Coherence CE Docker image; it contains 
everything necessary for the client to operate correctly.

```bash
docker run -d -p 1408:1408 -p 30000:30000 ghcr.io/oracle/coherence-ce:25.03.2
```

## Installation

```bash
go get github.com/oracle/coherence-go-client/v2@latest
````

## <a name="doc"></a>Documentation

* [Go Client API Reference for Oracle Coherence](https://pkg.go.dev/github.com/oracle/coherence-go-client/v2/coherence)
* [FAQ Page](https://github.com/oracle/coherence-go-client/wiki/FAQ)
* [Troubleshooting Guide](https://github.com/oracle/coherence-go-client/wiki/Troubleshooting)

## <a name="examples"></a>Examples

For a comprehensive set of Go client API examples, please see [examples](examples).

The following example connects to a Coherence cluster running gRPC Proxy on default
port of 1408, creates a new `NamedMap` with key `int` and value of a `string` and
issues `Put()`, `Get()` and `Size()` operations.

> Note: Keys and values can also be Go `structs`. See detailed examples [here](examples#basic).

```go
package main

import (
    "context"
    "fmt"
    "github.com/oracle/coherence-go-client/v2/coherence"
)

func main() {
    var (
        value *string
        ctx   = context.Background()
    )

    // create a new Session to the default gRPC port of 1408
    session, err := coherence.NewSession(ctx, coherence.WithPlainText())
    if err != nil {
        panic(err)
    }
    defer session.Close()

    // get a NamedMap with key of int and value of string
    namedMap, err := coherence.GetNamedMap[int, string](session, "my-map")
    if err != nil {
        panic(err)
    }

    // put a new key / value
    if _, err = namedMap.Put(ctx, 1, "one"); err != nil {
        panic(err)
    }
	
    // get the value for key 1
    if value, err = namedMap.Get(ctx, 1); err != nil {
       panic(err)
    }
    fmt.Println("Value for key 1 is", *value)

    // update the value for key 1
    if _, err = namedMap.Put(ctx, 1, "ONE"); err != nil {
        panic(err)
    }

    // get the updated value for key 1
    if value, err = namedMap.Get(ctx, 1); err != nil {
        panic(err)
    }
    fmt.Println("Updated value is", *value)

    // remove the entry
    if _, err = namedMap.Remove(ctx, 1); err != nil {
        panic(err)
    }
}
```

## Help

We have a **public Slack channel** where you can get in touch with us to ask questions about using the Coherence Go client as well as give us feedback or suggestions about what features and improvements you would like to see. We would love
to hear from you. To join our channel,
please [visit this site to get an invitation](https://join.slack.com/t/oraclecoherence/shared_invite/enQtNzcxNTQwMTAzNjE4LTJkZWI5ZDkzNGEzOTllZDgwZDU3NGM2YjY5YWYwMzM3ODdkNTU2NmNmNDFhOWIxMDZlNjg2MzE3NmMxZWMxMWE).  
The invitation email will include details of how to access our Slack
workspace.  After you are logged in, please come to `#coherence` and say, "hello!"

If you would like to raise an issue please see [here](https://github.com/oracle/coherence-go-client/issues/new/choose).

You may also find your question is already answered on our [FAQ](https://github.com/oracle/coherence-go-client/wiki/FAQ) or
[troubleshooting](https://github.com/oracle/coherence-go-client/wiki/Troubleshooting) Wiki.

## Contributing

This project welcomes contributions from the community. Before submitting a pull request, please [review our contribution guide](./CONTRIBUTING.md)

## Security

Please consult the [security guide](./SECURITY.md) for our responsible security vulnerability disclosure process.

## License

Copyright (c) 2024 Oracle and/or its affiliates.

Released under the Universal Permissive License v1.0 as shown at
<https://oss.oracle.com/licenses/upl/>.



coherence-go-client

Embeddable Distributed in-memory data store compatible with Redis clients

[![Go](https://github.com/EchoVault/SugarDB/workflows/Go/badge.svg)]() 
[![Go Report Card](https://goreportcard.com/badge/github.com/echovault/echovault)](https://goreportcard.com/report/github.com/echovault/echovault)
[![codecov](https://codecov.io/gh/EchoVault/SugarDB/graph/badge.svg?token=CHWTW0IUNV)](https://codecov.io/gh/EchoVault/SugarDB)
<br/>
[![Go Reference](https://pkg.go.dev/badge/github.com/echovault/echovault.svg)](https://pkg.go.dev/github.com/echovault/sugardb)
[![GitHub Release](https://img.shields.io/github/v/release/EchoVault/SugarDB)]()
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
<br/>
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go) 
[![Discord](https://img.shields.io/discord/1211815152291414037?label=Discord&labelColor=%237289da)](https://discord.com/invite/JrG4kPrF8v)
<br/>

<hr/>

# Table of Contents
1. [What is SugarDB](#what-is-sugardb)
2. [Features](#features)
3. [Usage (Embedded)](#usage-embedded)
4. [Usage (Client-Server)](#usage-client-server)
   1. [Homebrew](#usage-homebrew)
   2. [Docker](#usage-docker)
   3. [GitHub Container Registry](#usage-container-registry)
   4. [Binaries](#usage-binaries)
5. [Clients](#clients)
6. [Benchmarks](#benchmarks)
7. [Commands](#commands)
   1. [ACL](#commands-acl)
   2. [ADMIN](#commands-admin)
   3. [CONNECTION](#commands-connection)
   4. [GENERIC](#commands-generic)
   5. [HASH](#commands-hash)
   6. [LIST](#commands-list)
   7. [PUBSUB](#commands-pubsub)
   8. [SET](#commands-set)
   9. [SORTED SET](#commands-sortedset)
   10. [STRING](#commands-string)

<a name="what-is-sugardb"></a>
# What is SugarDB?

SugarDB is a highly configurable, distributed, in-memory data store and cache implemented in Go.
It can be imported as a Go library or run as an independent service.

SugarDB aims to provide a rich set of data structures and functions for
manipulating data in memory. These data structures include, but are not limited to:
Lists, Sets, Sorted Sets, Hashes, and much more to come soon.

SugarDB provides a persistence layer for increased reliability. Both Append-Only files 
and snapshots can be used to persist data in the disk for recovery in case of unexpected shutdowns.

Replication is a core feature of SugarDB and is implemented using the RAFT algorithm, 
allowing you to create a fault-tolerant cluster of SugarDB nodes to improve reliability.
If you do not need a replication cluster, you can always run SugarDB
in standalone mode and have a fully capable single node.

SugarDB aims to not only be a server but to be importable to existing 
projects to enhance them with SugarDB features, this 
capability is always being worked on and improved.

<a name="features"></a>
# Features

Features offered by SugarDB include:

1) TLS and mTLS support for multiple server and client RootCAs.
2) Replication cluster support using the RAFT algorithm.
3) ACL Layer for user Authentication and Authorization.
4) Distributed Pub/Sub functionality.
5) Sets, Sorted Sets, Hashes, Lists and more.
6) Persistence layer with Snapshots and Append-Only files.
7) Key Eviction Policies.
8) Command extension via shared object files.
9) Command extension via embedded API.
10) Command extension via Lua Modules.
11) Command extension via JavaScript Modules.
12) Multi-database support for key namespacing.

We are working hard to add more features to SugarDB to make it
much more powerful. Features in the roadmap include:

1) Sharding
2) Streams
3) Transactions
4) Bitmap
5) HyperLogLog
6) JSON
7) Improved Observability
   

<a name="usage-embedded"></a>
# Usage (Embedded)

Install SugarDB with: `go get github.com/echovault/sugardb/sugardb`.

Here's an example of using SugarDB as an embedded library.
You can access all of SugarDB's commands using an ergonomic API.

```go
func main() {
  server, err := sugardb.NewSugarDB()
  if err != nil {
    log.Fatal(err)
  }

  _, _, _ = server.Set("key", "Hello, SugarDB!", sugardb.SETOptions{})

  v, _ := server.Get("key")
  fmt.Println(v) // Hello, SugarDB!

  // (Optional): Listen for TCP connections on this SugarDB instance.
  server.Start()
}
```

An embedded SugarDB instance can still be part of a cluster, and the changes triggered 
from the API will be consistent across the cluster.

<a name="usage-client-server"></a>
# Usage (Client-Server) 

<a name="usage-homebrew"></a>
### Homebrew

To install via homebrew, run:
1) `brew tap echovault/sugardb`
2) `brew install echovault/echovault/sugardb`

Once installed, you can run the server with the following command:
`sugardb --bind-addr=localhost --data-dir="path/to/persistence/directory"`

<a name="usage-docker"></a>
### Docker

`docker pull echovault/sugardb`

The full list of tags can be found [here](https://hub.docker.com/r/echovault/sugardb/tags).

<a name="usage-container-registry"></a>
### Container Registry

`docker pull ghcr.io/echovault/sugardb`

The full list of tags can be found [here](https://github.com/EchoVault/SugarDB/pkgs/container/sugardb).

<a name="usage-binaries"></a>
### Binaries

You can download the binaries by clicking on a release tag and downloading
the binary for your system.

<a name="clients"></a>
# Clients

SugarDB uses RESP, which makes it compatible with existing 
Redis clients.

<a name="benchmarks"></a>
# Benchmarks
To compare command performance with Redis, benchmarks can be run with: 

`make benchmark`

Prerequisites:
- `brew install redis` to run the Redis server and benchmark script
- `brew tap echovault/sugardb` & `brew install echovault/echovault/sugardb` to run the SugarDB Client-Server

Benchmark script options:
- `make benchmark use_local_server=true` runs on your local SugarDB Client-Server
- `make benchmark commands=ping,set,get...` runs the benchmark script on the specified commands

<a name="commands"></a>
# Supported Commands

<a name="commands-acl"></a>
## ACL
* [ACL CAT](https://sugardb.io/docs/commands/acl/acl_cat)
* [ACL DELUSER](https://sugardb.io/docs/commands/acl/acl_deluser)
* [ACL GETUSER](https://sugardb.io/docs/commands/acl/acl_getuser)
* [ACL LIST](https://sugardb.io/docs/commands/acl/acl_list)
* [ACL LOAD](https://sugardb.io/docs/commands/acl/acl_load)
* [ACL SAVE](https://sugardb.io/docs/commands/acl/acl_save)
* [ACL SETUSER](https://sugardb.io/docs/commands/acl/acl_setuser)
* [ACL USERS](https://sugardb.io/docs/commands/acl/acl_users)
* [ACL WHOAMI](https://sugardb.io/docs/commands/acl/acl_whoami)

<a name="commands-admin"></a>
## ADMIN
* [COMMAND COUNT](https://sugardb.io/docs/commands/admin/command_count)
* [COMMAND LIST](https://sugardb.io/docs/commands/admin/command_list)
* [COMMANDS](https://sugardb.io/docs/commands/admin/commands)
* [LASTSAVE](https://sugardb.io/docs/commands/admin/lastsave)
* [MODULE LIST](https://sugardb.io/docs/commands/admin/module_list)
* [MODULE LOAD](https://sugardb.io/docs/commands/admin/module_load)
* [MODULE UNLOAD](https://sugardb.io/docs/commands/admin/module_unload)
* [REWRITEAOF](https://sugardb.io/docs/commands/admin/rewriteaof)
* [SAVE](https://sugardb.io/docs/commands/admin/save)

<a name="commands-connection"></a>
## CONNECTION
* [AUTH](https://sugardb.io/docs/commands/connection/auth)
* [ECHO](https://sugardb.io/docs/commands/connection/echo)
* [HELLO](https://sugardb.io/docs/commands/connection/hello)
* [PING](https://sugardb.io/docs/commands/connection/ping)
* [SELECT](https://sugardb.io/docs/commands/connection/select)
* [SWAPDB](https://sugardb.io/docs/commands/connection/swapdb)

<a name="commands-generic"></a>
## GENERIC
* [COPY](https://sugardb.io/docs/commands/generic/copy)
* [DBSIZE](https://sugardb.io/docs/commands/generic/dbsize)
* [DECR](https://sugardb.io/docs/commands/generic/decr)
* [DECRBY](https://sugardb.io/docs/commands/generic/decrby)
* [DEL](https://sugardb.io/docs/commands/generic/del)
* [EXISTS](https://sugardb.io/docs/commands/generic/exists)
* [EXPIRE](https://sugardb.io/docs/commands/generic/expire)
* [EXPIRETIME](https://sugardb.io/docs/commands/generic/expiretime)
* [FLUSHALL](https://sugardb.io/docs/commands/generic/flushall)
* [FLUSHDB](https://sugardb.io/docs/commands/generic/flushdb)
* [GET](https://sugardb.io/docs/commands/generic/get)
* [GETDEL](https://sugardb.io/docs/commands/generic/getdel)
* [GETEX](https://sugardb.io/docs/commands/generic/get)
* [INCR](https://sugardb.io/docs/commands/generic/incr)
* [INCRBY](https://sugardb.io/docs/commands/generic/incrby)
* [INCRBYFLOAT](https://sugardb.io/docs/commands/generic/incrbyfloat)
* [KEYS](https://sugardb.io/docs/commands/generic/keys)
* [MGET](https://sugardb.io/docs/commands/generic/mget)
* [MOVE](https://sugardb.io/docs/commands/generic/move)
* [MSET](https://sugardb.io/docs/commands/generic/mset)
* [OBJECTFREQ](https://sugardb.io/docs/commands/generic/objectfreq)
* [OBJECTIDLETIME](https://sugardb.io/docs/commands/generic/objectidletime)
* [PERSIST](https://sugardb.io/docs/commands/generic/persist)
* [PEXPIRE](https://sugardb.io/docs/commands/generic/pexpire)
* [PEXPIREAT](https://sugardb.io/docs/commands/generic/pexpireat)
* [PEXPIRETIME](https://sugardb.io/docs/commands/generic/pexpiretime)
* [PTTL](https://sugardb.io/docs/commands/generic/pttl)
* [RANDOMKEY](https://sugardb.io/docs/commands/generic/randomkey)
* [RENAME](https://sugardb.io/docs/commands/generic/rename)
* [SET](https://sugardb.io/docs/commands/generic/set)
* [TTL](https://sugardb.io/docs/commands/generic/ttl)
* [TYPE](https://sugardb.io/docs/commands/generic/type)


<a name="commands-hash"></a>
## HASH
* [HDEL](https://sugardb.io/docs/commands/hash/hdel)
* [HEXISTS](https://sugardb.io/docs/commands/hash/hexists)
* [HEXPIRE](https://sugardb.io/docs/commands/hash/hexpire)
* [HGET](https://sugardb.io/docs/commands/hash/hget)
* [HGETALL](https://sugardb.io/docs/commands/hash/hgetall)
* [HINCRBY](https://sugardb.io/docs/commands/hash/hincrby)
* [HINCRBYFLOAT](https://sugardb.io/docs/commands/hash/hincrbyfloat)
* [HKEYS](https://sugardb.io/docs/commands/hash/hkeys)
* [HLEN](https://sugardb.io/docs/commands/hash/hlen)
* [HMGET](https://sugardb.io/docs/commands/hash/hmget)
* [HRANDFIELD](https://sugardb.io/docs/commands/hash/hrandfield)
* [HSET](https://sugardb.io/docs/commands/hash/hset)
* [HSETNX](https://sugardb.io/docs/commands/hash/hsetnx)
* [HSTRLEN](https://sugardb.io/docs/commands/hash/hstrlen)
* [HTTL](https://sugardb.io/docs/commands/hash/httl)
* [HVALS](https://sugardb.io/docs/commands/hash/hvals)

<a name="commands-list"></a>
## LIST
* [LINDEX](https://sugardb.io/docs/commands/list/lindex)
* [LLEN](https://sugardb.io/docs/commands/list/llen)
* [LMOVE](https://sugardb.io/docs/commands/list/lmove)
* [LPOP](https://sugardb.io/docs/commands/list/lpop)
* [LPUSH](https://sugardb.io/docs/commands/list/lpush)
* [LPUSHX](https://sugardb.io/docs/commands/list/lpushx)
* [LRANGE](https://sugardb.io/docs/commands/list/lrange)
* [LREM](https://sugardb.io/docs/commands/list/lrem)
* [LSET](https://sugardb.io/docs/commands/list/lset)
* [LTRIM](https://sugardb.io/docs/commands/list/ltrim)
* [RPOP](https://sugardb.io/docs/commands/list/rpop)
* [RPUSH](https://sugardb.io/docs/commands/list/rpush)
* [RPUSHX](https://sugardb.io/docs/commands/list/rpushx)

<a name="commands-pubsub"></a>
## PUBSUB
* [PSUBSCRIBE](https://sugardb.io/docs/commands/pubsub/psubscribe)
* [PUBLISH](https://sugardb.io/docs/commands/pubsub/publish)
* [PUBSUB CHANNELS](https://sugardb.io/docs/commands/pubsub/pubsub_channels)
* [PUBSUB NUMPAT](https://sugardb.io/docs/commands/pubsub/pubsub_numpat)
* [PUBSUB NUMSUB](https://sugardb.io/docs/commands/pubsub/pubsub_numsub)
* [PUNSUBSCRIBE](https://sugardb.io/docs/commands/pubsub/punsubscribe)
* [SUBSCRIBE](https://sugardb.io/docs/commands/pubsub/subscribe)
* [UNSUBSCRIBE](https://sugardb.io/docs/commands/pubsub/unsubscribe)

<a name="commands-set"></a>
## SET
* [SADD](https://sugardb.io/docs/commands/set/sadd)
* [SCARD](https://sugardb.io/docs/commands/set/scard)
* [SDIFF](https://sugardb.io/docs/commands/set/sdiff)
* [SDIFFSTORE](https://sugardb.io/docs/commands/set/sdiffstore)
* [SINTER](https://sugardb.io/docs/commands/set/sinter)
* [SINTERCARD](https://sugardb.io/docs/commands/set/sintercard)
* [SINTERSTORE](https://sugardb.io/docs/commands/set/sinterstore)
* [SISMEMBER](https://sugardb.io/docs/commands/set/sismember)
* [SMEMBERS](https://sugardb.io/docs/commands/set/smembers)
* [SMISMEMBER](https://sugardb.io/docs/commands/set/smismember)
* [SMOVE](https://sugardb.io/docs/commands/set/smove)
* [SPOP](https://sugardb.io/docs/commands/set/spop)
* [SRANDMEMBER](https://sugardb.io/docs/commands/set/srandmember)
* [SREM](https://sugardb.io/docs/commands/set/srem)
* [SUNION](https://sugardb.io/docs/commands/set/sunion)
* [SUNIONSTORE](https://sugardb.io/docs/commands/set/sunionstore)

<a name="commands-sortedset"></a>
## SORTED SET
* [ZADD](https://sugardb.io/docs/commands/sorted_set/zadd)
* [ZCARD](https://sugardb.io/docs/commands/sorted_set/zcard)
* [ZCOUNT](https://sugardb.io/docs/commands/sorted_set/zcount)
* [ZDIFF](https://sugardb.io/docs/commands/sorted_set/zdiff)
* [ZDIFFSTORE](https://sugardb.io/docs/commands/sorted_set/zdiffstore)
* [ZINCRBY](https://sugardb.io/docs/commands/sorted_set/zincrby)
* [ZINTER](https://sugardb.io/docs/commands/sorted_set/zinter)
* [ZINTERSTORE](https://sugardb.io/docs/commands/sorted_set/zinterstore)
* [ZLEXCOUNT](https://sugardb.io/docs/commands/sorted_set/zlexcount)
* [ZMPOP](https://sugardb.io/docs/commands/sorted_set/zmpop)
* [ZMSCORE](https://sugardb.io/docs/commands/sorted_set/zmscore)
* [ZPOPMAX](https://sugardb.io/docs/commands/sorted_set/zpopmax)
* [ZPOPMIN](https://sugardb.io/docs/commands/sorted_set/zpopmin)
* [ZRANDMEMBER](https://sugardb.io/docs/commands/sorted_set/zrandmember)
* [ZRANGE](https://sugardb.io/docs/commands/sorted_set/zrange)
* [ZRANGESTORE](https://sugardb.io/docs/commands/sorted_set/zrangestore)
* [ZRANK](https://sugardb.io/docs/commands/sorted_set/zrank)
* [ZREM](https://sugardb.io/docs/commands/sorted_set/zrem)
* [ZREMRANGEBYLEX](https://sugardb.io/docs/commands/sorted_set/zremrangebylex)
* [ZREMRANGEBYRANK](https://sugardb.io/docs/commands/sorted_set/zremrangebyrank)
* [ZREMRANGEBYSCORE](https://sugardb.io/docs/commands/sorted_set/zremrangebyscore)
* [ZREVRANK](https://sugardb.io/docs/commands/sorted_set/zrevrank)
* [ZSCORE](https://sugardb.io/docs/commands/sorted_set/zscore)
* [ZUNION](https://sugardb.io/docs/commands/sorted_set/zunion)
* [ZUNIONSTORE](https://sugardb.io/docs/commands/sorted_set/zunionstore)

<a name="commands-string"></a>
## STRING
* [APPEND](https://sugardb.io/docs/commands/string/append)
* [GETRANGE](https://sugardb.io/docs/commands/string/getrange)
* [SETRANGE](https://sugardb.io/docs/commands/string/setrange)
* [STRLEN](https://sugardb.io/docs/commands/string/strlen)
* [SUBSTR](https://sugardb.io/docs/commands/string/substr)


EchoVault

fast thread-safe inmemory cache for big number of entries. Minimizes GC overhead

[![Build Status](https://github.com/VictoriaMetrics/fastcache/workflows/main/badge.svg)](https://github.com/VictoriaMetrics/fastcache/actions)
[![GoDoc](https://godoc.org/github.com/VictoriaMetrics/fastcache?status.svg)](http://godoc.org/github.com/VictoriaMetrics/fastcache)
[![Go Report](https://goreportcard.com/badge/github.com/VictoriaMetrics/fastcache)](https://goreportcard.com/report/github.com/VictoriaMetrics/fastcache)
[![codecov](https://codecov.io/gh/VictoriaMetrics/fastcache/branch/master/graph/badge.svg)](https://codecov.io/gh/VictoriaMetrics/fastcache)

# fastcache - fast thread-safe inmemory cache for big number of entries in Go

### Features

* Fast. Performance scales on multi-core CPUs. See benchmark results below.
* Thread-safe. Concurrent goroutines may read and write into a single
  cache instance.
* The fastcache is designed for storing big number of entries without
  [GC overhead](https://syslog.ravelin.com/further-dangers-of-large-heaps-in-go-7a267b57d487).
* Fastcache automatically evicts old entries when reaching the maximum cache size
  set on its creation.
* [Simple API](http://godoc.org/github.com/VictoriaMetrics/fastcache).
* Simple source code.
* Cache may be [saved to file](https://godoc.org/github.com/VictoriaMetrics/fastcache#Cache.SaveToFile)
  and [loaded from file](https://godoc.org/github.com/VictoriaMetrics/fastcache#LoadFromFile).
* Works on [Google AppEngine](https://cloud.google.com/appengine/docs/go/).


### Benchmarks

`Fastcache` performance is compared with [BigCache](https://github.com/allegro/bigcache), standard Go map
and [sync.Map](https://golang.org/pkg/sync/#Map).

```
GOMAXPROCS=4 go test github.com/VictoriaMetrics/fastcache -bench='Set|Get' -benchtime=10s
goos: linux
goarch: amd64
pkg: github.com/VictoriaMetrics/fastcache
BenchmarkBigCacheSet-4      	    2000	  10566656 ns/op	   6.20 MB/s	 4660369 B/op	       6 allocs/op
BenchmarkBigCacheGet-4      	    2000	   6902694 ns/op	   9.49 MB/s	  684169 B/op	  131076 allocs/op
BenchmarkBigCacheSetGet-4   	    1000	  17579118 ns/op	   7.46 MB/s	 5046744 B/op	  131083 allocs/op
BenchmarkCacheSet-4         	    5000	   3808874 ns/op	  17.21 MB/s	    1142 B/op	       2 allocs/op
BenchmarkCacheGet-4         	    5000	   3293849 ns/op	  19.90 MB/s	    1140 B/op	       2 allocs/op
BenchmarkCacheSetGet-4      	    2000	   8456061 ns/op	  15.50 MB/s	    2857 B/op	       5 allocs/op
BenchmarkStdMapSet-4        	    2000	  10559382 ns/op	   6.21 MB/s	  268413 B/op	   65537 allocs/op
BenchmarkStdMapGet-4        	    5000	   2687404 ns/op	  24.39 MB/s	    2558 B/op	      13 allocs/op
BenchmarkStdMapSetGet-4     	     100	 154641257 ns/op	   0.85 MB/s	  387405 B/op	   65558 allocs/op
BenchmarkSyncMapSet-4       	     500	  24703219 ns/op	   2.65 MB/s	 3426543 B/op	  262411 allocs/op
BenchmarkSyncMapGet-4       	    5000	   2265892 ns/op	  28.92 MB/s	    2545 B/op	      79 allocs/op
BenchmarkSyncMapSetGet-4    	    1000	  14595535 ns/op	   8.98 MB/s	 3417190 B/op	  262277 allocs/op
```

`MB/s` column here actually means `millions of operations per second`.
As you can see, `fastcache` is faster than the `BigCache` in all the cases.
`fastcache` is faster than the standard Go map and `sync.Map` on workloads
with inserts.


### Limitations

* Keys and values must be byte slices. Other types must be marshaled before
  storing them in the cache.
* Big entries with sizes exceeding 64KB must be stored via [distinct API](http://godoc.org/github.com/VictoriaMetrics/fastcache#Cache.SetBig).
* There is no cache expiration. Entries are evicted from the cache only
  on cache size overflow. Entry deadline may be stored inside the value in order
  to implement cache expiration.


### Architecture details

The cache uses ideas from [BigCache](https://github.com/allegro/bigcache):

* The cache consists of many buckets, each with its own lock.
  This helps scaling the performance on multi-core CPUs, since multiple
  CPUs may concurrently access distinct buckets.
* Each bucket consists of a `hash(key) -> (key, value) position` map
  and 64KB-sized byte slices (chunks) holding encoded `(key, value)` entries.
  Each bucket contains only `O(chunksCount)` pointers. For instance, 64GB cache
  would contain ~1M pointers, while similarly-sized `map[string][]byte`
  would contain ~1B pointers for short keys and values. This would lead to
  [huge GC overhead](https://syslog.ravelin.com/further-dangers-of-large-heaps-in-go-7a267b57d487).

64KB-sized chunks reduce memory fragmentation and the total memory usage comparing
to a single big chunk per bucket.
Chunks are allocated off-heap if possible. This reduces total memory usage because
GC collects unused memory more frequently without the need in `GOGC` tweaking.


### Users

* `Fastcache` has been extracted from [VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics) sources.
  See [this article](https://medium.com/devopslinks/victoriametrics-creating-the-best-remote-storage-for-prometheus-5d92d66787ac)
  for more info about `VictoriaMetrics`.


### FAQ

#### What is the difference between `fastcache` and other similar caches like [BigCache](https://github.com/allegro/bigcache) or [FreeCache](https://github.com/coocood/freecache)?

* `Fastcache` is faster. See benchmark results above.
* `Fastcache` uses less memory due to lower heap fragmentation. This allows
  saving many GBs of memory on multi-GB caches.
* `Fastcache` API [is simpler](http://godoc.org/github.com/VictoriaMetrics/fastcache).
  The API is designed to be used in zero-allocation mode.


#### Why `fastcache` doesn't support cache expiration?

Because we don't need cache expiration in [VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics).
Cached entries inside `VictoriaMetrics` never expire. They are automatically evicted on cache size overflow.

It is easy to implement cache expiration on top of `fastcache` by caching values
with marshaled deadlines and verifying deadlines after reading these values
from the cache.


#### Why `fastcache` doesn't support advanced features such as [thundering herd protection](https://en.wikipedia.org/wiki/Thundering_herd_problem) or callbacks on entries' eviction?

Because these features would complicate the code and would make it slower.
`Fastcache` source code is simple - just copy-paste it and implement the feature you want
on top of it.


fastcache

Cache library with support for expirable Cache, LFU, LRU and ARC

# GCache

![Test](https://github.com/bluele/gcache/workflows/Test/badge.svg)
[![GoDoc](https://godoc.org/github.com/bluele/gcache?status.svg)](https://pkg.go.dev/github.com/bluele/gcache?tab=doc)

Cache library for golang. It supports expirable Cache, LFU, LRU and ARC.

## Features

* Supports expirable Cache, LFU, LRU and ARC.

* Goroutine safe.

* Supports event handlers which evict, purge, and add entry. (Optional)

* Automatically load cache if it doesn't exists. (Optional)

## Install

```
$ go get github.com/bluele/gcache
```

## Example

### Manually set a key-value pair.

```go
package main

import (
  "github.com/bluele/gcache"
  "fmt"
)

func main() {
  gc := gcache.New(20).
    LRU().
    Build()
  gc.Set("key", "ok")
  value, err := gc.Get("key")
  if err != nil {
    panic(err)
  }
  fmt.Println("Get:", value)
}
```

```
Get: ok
```

### Manually set a key-value pair, with an expiration time.

```go
package main

import (
  "github.com/bluele/gcache"
  "fmt"
  "time"
)

func main() {
  gc := gcache.New(20).
    LRU().
    Build()
  gc.SetWithExpire("key", "ok", time.Second*10)
  value, _ := gc.Get("key")
  fmt.Println("Get:", value)

  // Wait for value to expire
  time.Sleep(time.Second*10)

  value, err := gc.Get("key")
  if err != nil {
    panic(err)
  }
  fmt.Println("Get:", value)
}
```

```
Get: ok
// 10 seconds later, new attempt:
panic: ErrKeyNotFound
```


### Automatically load value

```go
package main

import (
  "github.com/bluele/gcache"
  "fmt"
)

func main() {
  gc := gcache.New(20).
    LRU().
    LoaderFunc(func(key interface{}) (interface{}, error) {
      return "ok", nil
    }).
    Build()
  value, err := gc.Get("key")
  if err != nil {
    panic(err)
  }
  fmt.Println("Get:", value)
}
```

```
Get: ok
```

### Automatically load value with expiration

```go
package main

import (
  "fmt"
  "time"

  "github.com/bluele/gcache"
)

func main() {
  var evictCounter, loaderCounter, purgeCounter int
  gc := gcache.New(20).
    LRU().
    LoaderExpireFunc(func(key interface{}) (interface{}, *time.Duration, error) {
      loaderCounter++
      expire := 1 * time.Second
      return "ok", &expire, nil
    }).
    EvictedFunc(func(key, value interface{}) {
      evictCounter++
      fmt.Println("evicted key:", key)
    }).
    PurgeVisitorFunc(func(key, value interface{}) {
      purgeCounter++
      fmt.Println("purged key:", key)
    }).
    Build()
  value, err := gc.Get("key")
  if err != nil {
    panic(err)
  }
  fmt.Println("Get:", value)
  time.Sleep(1 * time.Second)
  value, err = gc.Get("key")
  if err != nil {
    panic(err)
  }
  fmt.Println("Get:", value)
  gc.Purge()
  if loaderCounter != evictCounter+purgeCounter {
    panic("bad")
  }
}
```

```
Get: ok
evicted key: key
Get: ok
purged key: key
```


## Cache Algorithm

  * Least-Frequently Used (LFU)

  Discards the least frequently used items first.

  ```go
  func main() {
    // size: 10
    gc := gcache.New(10).
      LFU().
      Build()
    gc.Set("key", "value")
  }
  ```

  * Least Recently Used (LRU)

  Discards the least recently used items first.

  ```go
  func main() {
    // size: 10
    gc := gcache.New(10).
      LRU().
      Build()
    gc.Set("key", "value")
  }
  ```

  * Adaptive Replacement Cache (ARC)

  Constantly balances between LRU and LFU, to improve the combined result.

  detail: http://en.wikipedia.org/wiki/Adaptive_replacement_cache

  ```go
  func main() {
    // size: 10
    gc := gcache.New(10).
      ARC().
      Build()
    gc.Set("key", "value")
  }
  ```

  * SimpleCache (Default)

  SimpleCache has no clear priority for evict cache. It depends on key-value map order.

  ```go
  func main() {
    // size: 10
    gc := gcache.New(10).Build()
    gc.Set("key", "value")
    v, err := gc.Get("key")
    if err != nil {
      panic(err)
    }
  }
  ```

## Loading Cache

If specified `LoaderFunc`, values are automatically loaded by the cache, and are stored in the cache until either evicted or manually invalidated.

```go
func main() {
  gc := gcache.New(10).
    LRU().
    LoaderFunc(func(key interface{}) (interface{}, error) {
      return "value", nil
    }).
    Build()
  v, _ := gc.Get("key")
  // output: "value"
  fmt.Println(v)
}
```

GCache coordinates cache fills such that only one load in one process of an entire replicated set of processes populates the cache, then multiplexes the loaded value to all callers.

## Expirable cache

```go
func main() {
  // LRU cache, size: 10, expiration: after a hour
  gc := gcache.New(10).
    LRU().
    Expiration(time.Hour).
    Build()
}
```

## Event handlers

### Evicted handler

Event handler for evict the entry.

```go
func main() {
  gc := gcache.New(2).
    EvictedFunc(func(key, value interface{}) {
      fmt.Println("evicted key:", key)
    }).
    Build()
  for i := 0; i < 3; i++ {
    gc.Set(i, i*i)
  }
}
```

```
evicted key: 0
```

### Added handler

Event handler for add the entry.

```go
func main() {
  gc := gcache.New(2).
    AddedFunc(func(key, value interface{}) {
      fmt.Println("added key:", key)
    }).
    Build()
  for i := 0; i < 3; i++ {
    gc.Set(i, i*i)
  }
}
```

```
added key: 0
added key: 1
added key: 2
```

# Author

**Jun Kimura**

* <http://github.com/bluele>
* <junkxdev@gmail.com>


GCache

A complete Go cache library with multiple stores (memory, memcache, redis, ...), chainable, loadable, metrics cache and more

[![Test](https://github.com/eko/gocache/actions/workflows/all.yml/badge.svg?branch=master)](https://github.com/eko/gocache/actions/workflows/all.yml)
[![GoDoc](https://godoc.org/github.com/eko/gocache?status.png)](https://pkg.go.dev/github.com/eko/gocache/lib/v4)
[![GoReportCard](https://goreportcard.com/badge/github.com/eko/gocache)](https://goreportcard.com/report/github.com/eko/gocache)
[![codecov](https://codecov.io/gh/eko/gocache/branch/master/graph/badge.svg)](https://codecov.io/gh/eko/gocache)

# Gocache

Guess what is Gocache? a Go cache library.
This is an extendable cache library that brings you a lot of features for caching data.

## Overview

Here is what it brings in detail:

- ✅ Multiple cache stores: actually in memory, redis, or your own custom store
- ✅ A chain cache: use multiple cache with a priority order (memory then fallback to a redis shared cache for instance)
- ✅ A loadable cache: allow you to call a callback function to put your data back in cache
- ✅ A metric cache to let you store metrics about your caches usage (hits, miss, set success, set error, ...)
- ✅ A marshaler to automatically marshal/unmarshal your cache values as a struct
- ✅ Define default values in stores and override them when setting data
- ✅ Cache invalidation by expiration time and/or using tags
- ✅ Use of Generics

## Built-in stores

- [Memory (bigcache)](https://github.com/allegro/bigcache) (allegro/bigcache)
- [Memory (ristretto)](https://github.com/dgraph-io/ristretto) (dgraph-io/ristretto)
- [Memory (go-cache)](https://github.com/patrickmn/go-cache) (patrickmn/go-cache)
- [Memcache](https://github.com/bradfitz/gomemcache) (bradfitz/memcache)
- [Redis](https://github.com/go-redis/redis) (go-redis/redis)
- [Redis (rueidis)](https://github.com/redis/rueidis) (redis/rueidis)
- [Freecache](https://github.com/coocood/freecache) (coocood/freecache)
- [Pegasus](https://pegasus.apache.org/) ([apache/incubator-pegasus](https://github.com/apache/incubator-pegasus)) [benchmark](https://pegasus.apache.org/overview/benchmark/)
- [Hazelcast](https://github.com/hazelcast/hazelcast-go-client) (hazelcast-go-client/hazelcast)
- More to come soon

## Built-in metrics providers

- [Prometheus](https://github.com/prometheus/client_golang)

## Installation

To begin working with the latest version of gocache, you can import the library in your project:

```go
go get github.com/eko/gocache/lib/v4
```

and then, import the store(s) you want to use between all available ones:

```go
go get github.com/eko/gocache/store/bigcache/v4
go get github.com/eko/gocache/store/freecache/v4
go get github.com/eko/gocache/store/go_cache/v4
go get github.com/eko/gocache/store/hazelcast/v4
go get github.com/eko/gocache/store/memcache/v4
go get github.com/eko/gocache/store/pegasus/v4
go get github.com/eko/gocache/store/redis/v4
go get github.com/eko/gocache/store/rediscluster/v4
go get github.com/eko/gocache/store/rueidis/v4
go get github.com/eko/gocache/store/ristretto/v4
```

Then, simply use the following import statements:

```go
import (
	"github.com/eko/gocache/lib/v4/cache"
	"github.com/eko/gocache/store/redis/v4"
)
```

If you run into any errors, please be sure to run `go mod tidy` to clean your go.mod file.

## Available cache features in detail

### A simple cache

Here is a simple cache instantiation with Redis but you can also look at other available stores:

#### Memcache

```go
memcacheStore := memcache_store.NewMemcache(
	memcache.New("10.0.0.1:11211", "10.0.0.2:11211", "10.0.0.3:11212"),
	store.WithExpiration(10*time.Second),
)

cacheManager := cache.New[[]byte](memcacheStore)
err := cacheManager.Set(ctx, "my-key", []byte("my-value"),
	store.WithExpiration(15*time.Second), // Override default value of 10 seconds defined in the store
)
if err != nil {
    panic(err)
}

value := cacheManager.Get(ctx, "my-key")

cacheManager.Delete(ctx, "my-key")

cacheManager.Clear(ctx) // Clears the entire cache, in case you want to flush all cache
```

#### Memory (using Bigcache)

```go
bigcacheClient, _ := bigcache.NewBigCache(bigcache.DefaultConfig(5 * time.Minute))
bigcacheStore := bigcache_store.NewBigcache(bigcacheClient)

cacheManager := cache.New[[]byte](bigcacheStore)
err := cacheManager.Set(ctx, "my-key", []byte("my-value"))
if err != nil {
    panic(err)
}

value := cacheManager.Get(ctx, "my-key")
```

#### Memory (using Ristretto)

```go
import (
	"github.com/dgraph-io/ristretto"
	"github.com/eko/gocache/lib/v4/cache"
	"github.com/eko/gocache/lib/v4/store"
	ristretto_store "github.com/eko/gocache/store/ristretto/v4"
)
ristrettoCache, err := ristretto.NewCache(&ristretto.Config[string, string]{
	NumCounters: 1000,
	MaxCost: 100,
	BufferItems: 64,
})
if err != nil {
    panic(err)
}
ristrettoStore := ristretto_store.NewRistretto(ristrettoCache)

cacheManager := cache.New[string](ristrettoStore)
err := cacheManager.Set(ctx, "my-key", "my-value", store.WithCost(2))
if err != nil {
    panic(err)
}

value := cacheManager.Get(ctx, "my-key")

cacheManager.Delete(ctx, "my-key")
```

#### Memory (using Go-cache)

```go
gocacheClient := gocache.New(5*time.Minute, 10*time.Minute)
gocacheStore := gocache_store.NewGoCache(gocacheClient)

cacheManager := cache.New[[]byte](gocacheStore)
err := cacheManager.Set(ctx, "my-key", []byte("my-value"))
if err != nil {
	panic(err)
}

value, err := cacheManager.Get(ctx, "my-key")
if err != nil {
	panic(err)
}
fmt.Printf("%s", value)
```

#### Redis

```go
redisStore := redis_store.NewRedis(redis.NewClient(&redis.Options{
	Addr: "127.0.0.1:6379",
}))

cacheManager := cache.New[string](redisStore)
err := cacheManager.Set(ctx, "my-key", "my-value", store.WithExpiration(15*time.Second))
if err != nil {
    panic(err)
}

value, err := cacheManager.Get(ctx, "my-key")
switch err {
	case nil:
		fmt.Printf("Get the key '%s' from the redis cache. Result: %s", "my-key", value)
	case redis.Nil:
		fmt.Printf("Failed to find the key '%s' from the redis cache.", "my-key")
	default:
	    fmt.Printf("Failed to get the value from the redis cache with key '%s': %v", "my-key", err)
}
```

#### [Redis Client-Side Caching](https://redis.io/docs/manual/client-side-caching/) (using rueidis)

```go
client, err := rueidis.NewClient(rueidis.ClientOption{InitAddress: []string{"127.0.0.1:6379"}})
if err != nil {
    panic(err)
}

cacheManager := cache.New[string](rueidis_store.NewRueidis(
    client,
    store.WithExpiration(15*time.Second),
    store.WithClientSideCaching(15*time.Second)),
)

if err = cacheManager.Set(ctx, "my-key", "my-value"); err != nil {
    panic(err)
}

value, err := cacheManager.Get(ctx, "my-key")
if err != nil {
    log.Fatalf("Failed to get the value from the redis cache with key '%s': %v", "my-key", err)
}
log.Printf("Get the key '%s' from the redis cache. Result: %s", "my-key", value)
```

#### Freecache

```go
freecacheStore := freecache_store.NewFreecache(freecache.NewCache(1000), store.WithExpiration(10 * time.Second))

cacheManager := cache.New[[]byte](freecacheStore)
err := cacheManager.Set(ctx, "by-key", []byte("my-value"), opts)
if err != nil {
    panic(err)
}

value := cacheManager.Get(ctx, "my-key")
```

#### Pegasus

```go
pegasusStore, err := pegasus_store.NewPegasus(&store.OptionsPegasus{
    MetaServers: []string{"127.0.0.1:34601", "127.0.0.1:34602", "127.0.0.1:34603"},
})

if err != nil {
    fmt.Println(err)
    return
}

cacheManager := cache.New[string](pegasusStore)
err = cacheManager.Set(ctx, "my-key", "my-value", store.WithExpiration(10 * time.Second))
if err != nil {
    panic(err)
}

value, _ := cacheManager.Get(ctx, "my-key")
```

#### Hazelcast

```go
hzClient, err := hazelcast.StartNewClient(ctx)
if err != nil {
    log.Fatalf("Failed to start client: %v", err)
}

hzMap, err := hzClient.GetMap(ctx, "gocache")
if err != nil {
    b.Fatalf("Failed to get map: %v", err)
}

hazelcastStore := hazelcast_store.NewHazelcast(hzMap)

cacheManager := cache.New[string](hazelcastStore)
err := cacheManager.Set(ctx, "my-key", "my-value", store.WithExpiration(15*time.Second))
if err != nil {
    panic(err)
}

value, err := cacheManager.Get(ctx, "my-key")
if err != nil {
    panic(err)
}
fmt.Printf("Get the key '%s' from the hazelcast cache. Result: %s", "my-key", value)
```

### A chained cache

Here, we will chain caches in the following order: first in memory with Ristretto store, then in Redis (as a fallback):

```go
// Initialize Ristretto cache and Redis client
ristrettoCache, err := ristretto.NewCache(&ristretto.Config[string, string]{
    NumCounters: 1000,
    MaxCost: 100,
    BufferItems: 64,
})
if err != nil {
    panic(err)
}

redisClient := redis.NewClient(&redis.Options{Addr: "127.0.0.1:6379"})

// Initialize stores
ristrettoStore := ristretto_store.NewRistretto(ristrettoCache)
redisStore := redis_store.NewRedis(redisClient, store.WithExpiration(5*time.Second))

// Initialize chained cache
cacheManager := cache.NewChain[any](
    cache.New[any](ristrettoStore),
    cache.New[any](redisStore),
)

// ... Then, do what you want with your cache
```

`Chain` cache also put data back in previous caches when it's found so in this case, if ristretto doesn't have the data in its cache but redis have, data will also get setted back into ristretto (memory) cache.

### A loadable cache

This cache will provide a load function that acts as a callable function and will set your data back in your cache in case they are not available:

```go
type Book struct {
	ID string
	Name string
}

// Initialize Redis client and store
redisClient := redis.NewClient(&redis.Options{Addr: "127.0.0.1:6379"})
redisStore := redis_store.NewRedis(redisClient)

// Initialize a load function that loads your data from a custom source
loadFunction := func(ctx context.Context, key any) (*Book, error) {
    // ... retrieve value from available source
    return &Book{ID: 1, Name: "My test amazing book"}, nil
}

// Initialize loadable cache
cacheManager := cache.NewLoadable[*Book](
	loadFunction,
	cache.New[*Book](redisStore),
)

// ... Then, you can get your data and your function will automatically put them in cache(s)
```

Of course, you can also pass a `Chain` cache into the `Loadable` one so if your data is not available in all caches, it will bring it back in all caches.

### A metric cache to retrieve cache statistics

This cache will record metrics depending on the metric provider you pass to it. Here we give a Prometheus provider:

```go
// Initialize Redis client and store
redisClient := redis.NewClient(&redis.Options{Addr: "127.0.0.1:6379"})
redisStore := redis_store.NewRedis(redisClient)

// Initializes Prometheus metrics service
promMetrics := metrics.NewPrometheus("my-test-app")

// Initialize metric cache
cacheManager := cache.NewMetric[any](
	promMetrics,
	cache.New[any](redisStore),
)

// ... Then, you can get your data and metrics will be observed by Prometheus
```

### A marshaler wrapper

Some caches like Redis stores and returns the value as a string so you have to marshal/unmarshal your structs if you want to cache an object. That's why we bring a marshaler service that wraps your cache and make the work for you:

```go
// Initialize Redis client and store
redisClient := redis.NewClient(&redis.Options{Addr: "127.0.0.1:6379"})
redisStore := redis_store.NewRedis(redisClient)

// Initialize chained cache
cacheManager := cache.NewMetric[any](
	promMetrics,
	cache.New[any](redisStore),
)

// Initializes marshaler
marshal := marshaler.New(cacheManager)

key := BookQuery{Slug: "my-test-amazing-book"}
value := Book{ID: 1, Name: "My test amazing book", Slug: "my-test-amazing-book"}

err = marshal.Set(ctx, key, value)
if err != nil {
    panic(err)
}

returnedValue, err := marshal.Get(ctx, key, new(Book))
if err != nil {
    panic(err)
}

// Then, do what you want with the  value

marshal.Delete(ctx, "my-key")
```

The only thing you have to do is to specify the struct in which you want your value to be un-marshalled as a second argument when calling the `.Get()` method.

### Cache invalidation using tags

You can attach some tags to items you create so you can easily invalidate some of them later.

Tags are stored using the same storage you choose for your cache.

Here is an example on how to use it:

```go
// Initialize Redis client and store
redisClient := redis.NewClient(&redis.Options{Addr: "127.0.0.1:6379"})
redisStore := redis_store.NewRedis(redisClient)

// Initialize chained cache
cacheManager := cache.NewMetric[*Book](
	promMetrics,
	cache.New[*Book](redisStore),
)

// Initializes marshaler
marshal := marshaler.New(cacheManager)

key := BookQuery{Slug: "my-test-amazing-book"}
value := &Book{ID: 1, Name: "My test amazing book", Slug: "my-test-amazing-book"}

// Set an item in the cache and attach it a "book" tag
err = marshal.Set(ctx, key, value, store.WithTags([]string{"book"}))
if err != nil {
    panic(err)
}

// Remove all items that have the "book" tag
err := marshal.Invalidate(ctx, store.WithInvalidateTags([]string{"book"}))
if err != nil {
    panic(err)
}

returnedValue, err := marshal.Get(ctx, key, new(Book))
if err != nil {
	// Should be triggered because item has been deleted so it cannot be found.
    panic(err)
}
```

Mix this with expiration times on your caches to have a fine-tuned control on how your data are cached.

```go
package main

import (
	"fmt"
	"log"
	"time"

	"github.com/eko/gocache/lib/v4/cache"
	"github.com/eko/gocache/lib/v4/store"
	"github.com/redis/go-redis/v9"
)

func main() {
	redisStore := redis_store.NewRedis(redis.NewClient(&redis.Options{
		Addr: "127.0.0.1:6379",
	}), nil)

	cacheManager := cache.New[string](redisStore)
	err := cacheManager.Set(ctx, "my-key", "my-value", store.WithExpiration(15*time.Second))
	if err != nil {
		panic(err)
	}

	key := "my-key"
	value, err := cacheManager.Get(ctx, key)
	if err != nil {
		log.Fatalf("unable to get cache key '%s' from the cache: %v", key, err)
	}

	fmt.Printf("%#+v\n", value)
}

```

### Write your own custom cache

Cache respect the following interface so you can write your own (proprietary?) cache logic if needed by implementing the following interface:

```go
type CacheInterface[T any] interface {
	Get(ctx context.Context, key any) (T, error)
	Set(ctx context.Context, key any, object T, options ...store.Option) error
	Delete(ctx context.Context, key any) error
	Invalidate(ctx context.Context, options ...store.InvalidateOption) error
	Clear(ctx context.Context) error
	GetType() string
}
```

Or, in case you use a setter cache, also implement the `GetCodec()` method:

```go
type SetterCacheInterface[T any] interface {
	CacheInterface[T]
	GetWithTTL(ctx context.Context, key any) (T, time.Duration, error)

	GetCodec() codec.CodecInterface
}
```

As all caches available in this library implement `CacheInterface`, you will be able to mix your own caches with your own.

### Write your own custom store

You also have the ability to write your own custom store by implementing the following interface:

```go
type StoreInterface interface {
	Get(ctx context.Context, key any) (any, error)
	GetWithTTL(ctx context.Context, key any) (any, time.Duration, error)
	Set(ctx context.Context, key any, value any, options ...Option) error
	Delete(ctx context.Context, key any) error
	Invalidate(ctx context.Context, options ...InvalidateOption) error
	Clear(ctx context.Context) error
	GetType() string
}
```

Of course, I suggest you to have a look at current caches or stores to implement your own.

### Custom cache key generator

You can implement the following interface in order to generate a custom cache key:

```go
type CacheKeyGenerator interface {
	GetCacheKey() string
}
```

### Benchmarks

![Benchmarks](https://raw.githubusercontent.com/eko/gocache/master/lib/misc/benchmarks.jpeg)

## Run tests

To generate mocks using mockgen library, run:

```bash
$ make mocks
```

Test suite can be run with:

```bash
$ make test # run unit test
```

## Community

Please feel free to contribute on this library and do not hesitate to open an issue if you want to discuss about a feature.


gocache

Groupcache is a caching and cache-filling library, intended as a replacement for memcached in many cases

# groupcache

## Summary

groupcache is a distributed caching and cache-filling library, intended as a
replacement for a pool of memcached nodes in many cases.

For API docs and examples, see http://godoc.org/github.com/golang/groupcache

## Comparison to memcached

### **Like memcached**, groupcache:

 * shards by key to select which peer is responsible for that key

### **Unlike memcached**, groupcache:

 * does not require running a separate set of servers, thus massively
   reducing deployment/configuration pain.  groupcache is a client
   library as well as a server.  It connects to its own peers, forming
   a distributed cache.

 * comes with a cache filling mechanism.  Whereas memcached just says
   "Sorry, cache miss", often resulting in a thundering herd of
   database (or whatever) loads from an unbounded number of clients
   (which has resulted in several fun outages), groupcache coordinates
   cache fills such that only one load in one process of an entire
   replicated set of processes populates the cache, then multiplexes
   the loaded value to all callers.

 * does not support versioned values.  If key "foo" is value "bar",
   key "foo" must always be "bar".  There are neither cache expiration
   times, nor explicit cache evictions.  Thus there is also no CAS,
   nor Increment/Decrement.  This also means that groupcache....

 * ... supports automatic mirroring of super-hot items to multiple
   processes.  This prevents memcached hot spotting where a machine's
   CPU and/or NIC are overloaded by very popular keys/values.

 * is currently only available for Go.  It's very unlikely that I
   (bradfitz@) will port the code to any other language.

## Loading process

In a nutshell, a groupcache lookup of **Get("foo")** looks like:

(On machine #5 of a set of N machines running the same code)

 1. Is the value of "foo" in local memory because it's super hot?  If so, use it.

 2. Is the value of "foo" in local memory because peer #5 (the current
    peer) is the owner of it?  If so, use it.

 3. Amongst all the peers in my set of N, am I the owner of the key
    "foo"?  (e.g. does it consistent hash to 5?)  If so, load it.  If
    other callers come in, via the same process or via RPC requests
    from peers, they block waiting for the load to finish and get the
    same answer.  If not, RPC to the peer that's the owner and get
    the answer.  If the RPC fails, just load it locally (still with
    local dup suppression).

## Users

groupcache is in production use by dl.google.com (its original user),
parts of Blogger, parts of Google Code, parts of Google Fiber, parts
of Google production monitoring systems, etc.

## Presentations

See http://talks.golang.org/2013/oscon-dl.slide

## Help

Use the golang-nuts mailing list for any discussion or questions.


groupcache

A High Performance, Generic, thread-safe, zero-dependency cache package

# icache

![example workflow](https://github.com/mdaliyan/icache/actions/workflows/test.yml/badge.svg)
[![Coverage Status](https://coveralls.io/repos/github/mdaliyan/icache/badge.svg?branch=master)](https://coveralls.io/github/mdaliyan/icache?branch=master)
[![Go Report Card](https://goreportcard.com/badge/github.com/mdaliyan/icache/v2)](https://goreportcard.com/report/github.com/mdaliyan/icache/v2)
[![Go Reference](https://pkg.go.dev/badge/github.com/mdaliyan/icache/v2.svg)](https://pkg.go.dev/github.com/mdaliyan/icache/v2)
[![License](http://img.shields.io/badge/license-mit-blue.svg?style=flat)](https://raw.githubusercontent.com/labstack/echo/master/LICENSE)

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.
```bash
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](https://github.com/mdaliyan/icache/tree/v1) for installation and usage. 
V1 will be maintained separately.

## Usage

```go 
// 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
```bash
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


icache

A generic in-memory cache Go library. It supports expiration, sliding expiration, max entries limit, eviction callbacks and sharding

imcache

A Go caching framework that supports multiple data source drivers

# nscache

[![Build](https://img.shields.io/github/actions/workflow/status/no-src/nscache/go.yml?branch=main)](https://github.com/no-src/nscache/actions)
[![License](https://img.shields.io/github/license/no-src/nscache)](https://github.com/no-src/nscache/blob/main/LICENSE)
[![Go Reference](https://pkg.go.dev/badge/github.com/no-src/nscache.svg)](https://pkg.go.dev/github.com/no-src/nscache)
[![Go Report Card](https://goreportcard.com/badge/github.com/no-src/nscache)](https://goreportcard.com/report/github.com/no-src/nscache)
[![codecov](https://codecov.io/gh/no-src/nscache/branch/main/graph/badge.svg?token=ol5hru7WCf)](https://codecov.io/gh/no-src/nscache)
[![Release](https://img.shields.io/github/v/release/no-src/nscache)](https://github.com/no-src/nscache/releases)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)

## Installation

```bash
go get -u github.com/no-src/nscache
```

## Quick Start

First, you need to import the cache driver, then create your cache component instance with the specified connection
string and use it.

Current support following cache drivers

| Driver        | Import Driver Package                     | Connection String Example                                                |
|---------------|-------------------------------------------|--------------------------------------------------------------------------|
| Memory        | `github.com/no-src/nscache/memory`        | `memory:`                                                                |
| Redis         | `github.com/no-src/nscache/redis`         | `redis://127.0.0.1:6379`                                                 |
| Redis Cluster | `github.com/no-src/nscache/redis_cluster` | `redis-cluster://127.0.0.1:7001?addr=127.0.0.1:7002&addr=127.0.0.1:7003` |
| BuntDB        | `github.com/no-src/nscache/buntdb`        | `buntdb://:memory:` or `buntdb://buntdb.db`                              |
| Etcd          | `github.com/no-src/nscache/etcd`          | `etcd://127.0.0.1:2379?dial_timeout=5s`                                  |
| BoltDB        | `github.com/no-src/nscache/boltdb`        | `boltdb://boltdb.db`                                                     |
| FreeCache     | `github.com/no-src/nscache/freecache`     | `freecache://?cache_size=50mib`                                          |
| BigCache      | `github.com/no-src/nscache/bigcache`      | `bigcache://?eviction=10m`                                               |
| FastCache     | `github.com/no-src/nscache/fastcache`     | `fastcache://?max_bytes=50mib`                                           |
| Memcached     | `github.com/no-src/nscache/memcached`     | `memcached://127.0.0.1:11211`                                            |
| Proxy         | `github.com/no-src/nscache/proxy/client`  | `proxy://127.0.0.1:8080`                                                 |

For example, initial a memory cache and write, read and remove data.

```go
package main

import (
	"time"

	_ "github.com/no-src/nscache/memory"

	"github.com/no-src/log"
	"github.com/no-src/nscache"
)

func main() {
	// initial cache driver
	c, err := nscache.NewCache("memory:")
	if err != nil {
		log.Error(err, "init cache error")
		return
	}
	defer c.Close()

	// write data
	k := "hello"
	c.Set(k, "world", time.Minute)

	// read data
	var v string
	if err = c.Get(k, &v); err != nil {
		log.Error(err, "get cache error")
		return
	}
	log.Info("key=%s value=%s", k, v)

	// remove data
	if err = c.Remove(k); err != nil {
		log.Error(err, "remove cache error")
		return
	}
}
```

## Command Line Tool

You can use the command line tool to operate all the cache drivers that `nscache` supports.

Install the command line tool `nscache-cli`.

```bash
go install github.com/no-src/nscache/cmd/nscache-cli@latest
```

Run the cli tool with specified cache driver connection string to operate cache.

```bash
nscache-cli memory:
```

## Proxy

### Proxy Server

Install the proxy server `nscache-server`.

```bash
go install github.com/no-src/nscache/cmd/nscache-server@latest
```

Run the proxy server with specified listen address and cache driver connection string.

```bash
nscache-server -addr=:8080 -conn=memory:
```

### Proxy Client

You can use the code to operate cache proxy server like the example code in the [Quick Start](#quick-start) section.

Or use the `nscache-cli` to connect to the proxy server and operate cache.

```bash
nscache-cli proxy://127.0.0.1:8080
```

nscache

A high performance lockless cache for Go. Many times faster than Ristretto and friends

<p align="center">
  <img src="docs/assets/logo.png" width="40%" height="auto" >
  <h2 align="center">In-memory caching library</h2>
</p>

<p align="center">
<a href="https://pkg.go.dev/github.com/maypok86/otter/v2"><img src="https://pkg.go.dev/badge/github.com/maypok86/otter/v2.svg" alt="Go Reference"></a>
<img src="https://github.com/maypok86/otter/actions/workflows/test.yml/badge.svg" />
<a href="https://github.com/maypok86/otter/actions?query=branch%3Amain+workflow%3ATest" >
    <img src="https://gist.githubusercontent.com/maypok86/2aae2cd39836dc7c258df7ffec602d1c/raw/coverage.svg"/></a>
<a href="https://github.com/maypok86/otter/releases"><img alt="GitHub Release" src="https://img.shields.io/github/v/release/maypok86/otter"></a>
<a href="https://github.com/avelino/awesome-go"><img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Go"></a>
</p>

Otter is designed to provide an excellent developer experience while maintaining high performance. It aims to address the shortcomings of its predecessors and incorporates design principles from high-performance libraries in other languages (such as [Caffeine](https://github.com/ben-manes/caffeine)).

## 📖 Contents

- [Features](#features)
- [Usage](#usage)
  - [Requirements](#requirements)
  - [Installation](#installation)
  - [Examples](#examples)
- [Performance](#performance)
  - [Throughput](#throughput)
  - [Hit ratio](#hit-ratio)
  - [Memory consumption](#memory-consumption)
- [Projects using Otter](#projects)
- [Related works](#related-works)
- [Contribute](#contribute)
- [License](#license)

## ✨ Features <a id="features" />

Performance-wise, Otter provides:

- [High hit rates](https://maypok86.github.io/otter/performance/hit-ratio/) across all workload types via [adaptive W-TinyLFU](https://dl.acm.org/citation.cfm?id=3274816)
- [Excellent throughput](https://maypok86.github.io/otter/performance/throughput/) under high contention on most workload types
- Among the lowest [memory overheads](https://maypok86.github.io/otter/performance/memory-consumption/) across all cache capacities
- Automatic data structures configuration based on contention/parallelism and workload patterns

Otter also provides a highly configurable caching API, enabling any combination of these optional features:

- Size-based [eviction](https://maypok86.github.io/otter/user-guide/v2/features/eviction/#size-based) when a maximum is exceeded
- Time-based [expiration](https://maypok86.github.io/otter/user-guide/v2/features/eviction/#time-based) of entries, measured since last access or last write
- [Automatic loading](https://maypok86.github.io/otter/user-guide/v2/features/loading/) of entries into the cache
- [Asynchronously refresh](https://maypok86.github.io/otter/user-guide/v2/features/refresh/) when the first stale request for an entry occurs
- [Writes propagated](https://maypok86.github.io/otter/user-guide/v2/features/compute/) to an external resource
-  Accumulation of cache access [statistics](https://maypok86.github.io/otter/user-guide/v2/features/statistics/)
- [Saving cache](https://maypok86.github.io/otter/user-guide/v2/features/persistence/) to a file and loading cache from a file

## 📚 Usage <a id="usage" />

For more details, see our [user's guide](https://maypok86.github.io/otter/user-guide/v2/getting-started/) and browse the [API docs](https://pkg.go.dev/github.com/maypok86/otter) for the latest release.

### 📋 Requirements <a id="requirements" />

Otter requires [Go](https://go.dev/) version [1.24](https://go.dev/doc/devel/release#go1.24.0) or above.

### 🛠️ Installation <a id="installation" />

#### With v1

```shell
go get -u github.com/maypok86/otter
```

#### With v2

```shell
go get -u github.com/maypok86/otter/v2
```

See the [release notes](https://github.com/maypok86/otter/releases) for details of the changes.

Note that otter only supports the two most recent minor versions of Go.

Otter follows semantic versioning for the documented public API on stable releases. `v2` is the latest stable major version.

### ✏️ Examples <a id="examples" />

Otter uses a plain `Options` struct for cache configuration. Check out [otter.Options](https://pkg.go.dev/github.com/maypok86/otter/v2#Options) for more details.

Note that all features are optional. You can create a cache that acts as a simple hash table wrapper, with near-zero memory overhead for unused features — thanks to [node code generation](https://github.com/maypok86/otter/blob/main/cmd/generator/main.go).

**API Usage Example**
```go
package main

import (
    "context"
    "time"

    "github.com/maypok86/otter/v2"
    "github.com/maypok86/otter/v2/stats"
)

func main() {
    ctx := context.Background()

    // Create statistics counter to track cache operations
    counter := stats.NewCounter()

    // Configure cache with:
    // - Capacity: 10,000 entries
    // - 1 second expiration after last access
    // - 500ms refresh interval after writes
    // - Stats collection enabled
    cache := otter.Must(&otter.Options[string, string]{
        MaximumSize:       10_000,
        ExpiryCalculator:  otter.ExpiryAccessing[string, string](time.Second),  // Reset timer on reads/writes
        RefreshCalculator: otter.RefreshWriting[string, string](500 * time.Millisecond),  // Refresh after writes
        StatsRecorder:     counter,  // Attach stats collector
    })

    // Phase 1: Test basic expiration
    // -----------------------------
    cache.Set("key", "value")  // Add initial value

    // Wait for expiration (1 second)
    time.Sleep(time.Second)

    // Verify entry expired
    if _, ok := cache.GetIfPresent("key"); ok {
        panic("key shouldn't be found")  // Should be expired
    }

    // Phase 2: Test cache stampede protection
    // --------------------------------------
    loader := func(ctx context.Context, key string) (string, error) {
        time.Sleep(200 * time.Millisecond)  // Simulate slow load
        return "value1", nil  // Return new value
    }

    // Concurrent Gets would deduplicate loader calls
    value, err := cache.Get(ctx, "key", otter.LoaderFunc[string, string](loader))
    if err != nil {
        panic(err)
    }
    if value != "value1" {
        panic("incorrect value")  // Should get newly loaded value
    }

    // Phase 3: Test background refresh
    // --------------------------------
    time.Sleep(500 * time.Millisecond)  // Wait until refresh needed

    // New loader that returns updated value
    loader = func(ctx context.Context, key string) (string, error) {
        time.Sleep(100 * time.Millisecond)  // Simulate refresh
        return "value2", nil  // Return refreshed value
    }

    // This triggers async refresh but returns current value
    value, err = cache.Get(ctx, "key", otter.LoaderFunc[string, string](loader))
    if err != nil {
        panic(err)
    }
    if value != "value1" {  // Should get old value while refreshing
        panic("loader shouldn't be called during Get")
    }

    // Wait for refresh to complete
    time.Sleep(110 * time.Millisecond)

    // Verify refreshed value
    v, ok := cache.GetIfPresent("key")
    if !ok {
        panic("key should be found")  // Should still be cached
    }
    if v != "value2" {  // Should now have refreshed value
        panic("refresh should be completed")
    }
}
```

You can find more usage examples [here](https://maypok86.github.io/otter/user-guide/v2/examples/).

## 📊 Performance <a id="performance" />

The benchmark code can be found [here](./benchmarks).

### 🚀 Throughput <a id="throughput" />

Throughput benchmarks are a Go port of the caffeine [benchmarks](https://github.com/ben-manes/caffeine/blob/master/caffeine/src/jmh/java/com/github/benmanes/caffeine/cache/GetPutBenchmark.java). This microbenchmark compares the throughput of caches on a zipf distribution, which allows to show various inefficient places in implementations.

You can find results [here](https://maypok86.github.io/otter/performance/throughput/).

### 🎯 Hit ratio <a id="hit-ratio" />

The hit ratio simulator tests caches on various traces:
1. Synthetic (Zipf distribution)
2. Traditional (widely known and used in various projects and papers)

You can find results [here](https://maypok86.github.io/otter/performance/hit-ratio/).

### 💾 Memory consumption <a id="memory-consumption" />

This benchmark quantifies the additional memory consumption across varying cache capacities.

You can find results [here](https://maypok86.github.io/otter/performance/memory-consumption/).

## 🏗️ Projects using Otter <a id="projects" />

Below is a list of known projects that use Otter:

- [Grafana](https://github.com/grafana/grafana): The open and composable observability and data visualization platform.
- [Centrifugo](https://github.com/centrifugal/centrifugo): Scalable real-time messaging server in a language-agnostic way.
- [FrankenPHP](https://github.com/php/frankenphp): The modern PHP app server.
- [Unkey](https://github.com/unkeyed/unkey): Open source API management platform.
- [Nuclei](https://github.com/projectdiscovery/nuclei): A fast, open-source, and highly customizable vulnerability scanner.
- [git-pages](https://codeberg.org/git-pages/git-pages): Scalable static page server for Git forges (like GitHub Pages or Netlify).

## 🗃 Related works <a id="related-works" />

Otter is based on the following papers:

- [BP-Wrapper: A Framework Making Any Replacement Algorithms (Almost) Lock Contention Free](https://www.researchgate.net/publication/220966845_BP-Wrapper_A_System_Framework_Making_Any_Replacement_Algorithms_Almost_Lock_Contention_Free)
- [TinyLFU: A Highly Efficient Cache Admission Policy](https://dl.acm.org/citation.cfm?id=3149371)
- [Adaptive Software Cache Management](https://dl.acm.org/citation.cfm?id=3274816)
- [Denial of Service via Algorithmic Complexity Attack](https://www.usenix.org/legacy/events/sec03/tech/full_papers/crosby/crosby.pdf)
- [Hashed and Hierarchical Timing Wheels](https://ieeexplore.ieee.org/document/650142)
- [A large scale analysis of hundreds of in-memory cache clusters at Twitter](https://www.usenix.org/system/files/osdi20-yang.pdf)

## 👏 Contribute <a id="contribute" />

Contributions are welcome as always, before submitting a new PR please make sure to open a new issue so community members can discuss it.
For more information please see [contribution guidelines](./CONTRIBUTING.md).

Additionally, you might find existing open issues which can help with improvements.

This project follows a standard [code of conduct](./CODE_OF_CONDUCT.md) so that you can understand what actions will and will not be tolerated.

## 📄 License <a id="license" />

This project is Apache 2.0 licensed, as found in the [LICENSE](./LICENSE).


otter

High performance, near optimal in-memory cache with proactive TTL expiration and generics

# Theine
[![Go Reference](https://pkg.go.dev/badge/github.com/Yiling-J/theine-go.svg)](https://pkg.go.dev/github.com/Yiling-J/theine-go)
[![codecov](https://codecov.io/gh/Yiling-J/theine-go/branch/main/graph/badge.svg?token=E1HJLJH07V)](https://codecov.io/gh/Yiling-J/theine-go)

High performance in-memory & hybrid cache inspired by [Caffeine](https://github.com/ben-manes/caffeine).


- Good performance
- Support for Generics
- High hit ratio with adaptive [W-TinyLFU](https://arxiv.org/pdf/1512.00727.pdf) eviction policy
- Expired data are removed automatically using [hierarchical timer wheel](http://www.cs.columbia.edu/~nahum/w6998/papers/ton97-timing-wheels.pdf)
- Simple API

## Table of Contents

- [Requirements](#requirements)
- [Installation](#installation)
- [API](#api)
- [Cache Persistence](#cache-persistence)
- [Benchmarks](#benchmarks)
  * [throughput](#throughput)
  * [hit ratios](#hit-ratios)
- [Secondary Cache(Experimental)](#secondary-cacheexperimental)
- [Support](#support)

## Requirements
Go 1.19+

## Installation
```
go get github.com/Yiling-J/theine-go
```

## API

**Builder API**

Theine provides two types of client, simple cache and loading cache. Both of them are initialized from a builder. The difference between simple cache and loading cache is: loading cache's Get method will compute the value using loader function when there is a miss, while simple cache client only return false and do nothing.

Loading cache uses [singleflight](https://pkg.go.dev/golang.org/x/sync/singleflight) to prevent concurrent loading to same key(thundering herd).

**Entry Pool**

Theine stores `*Entry` as the value in the hashmap, where each entry contains key, value, and metadata related to the policy. Before v0.6.0, Theine used a `sync pool` to automatically reuse evicted entries. This approach was beneficial for scenarios with heavy concurrent writes. If your system is already optimized for allocation, it should significantly reduce memory allocations. However, if cache writes are rare and GC is triggered often by other parts of your system, the sync pool becomes nearly useless.

And sync pool had a potential drawback: **race conditions within the policy**. Theine sends events to the policy asynchronously via channels/buffers, so there was a small chance that an event could be applied to the wrong entry if the entry was evicted and then reused by the pool.

To mitigate this, Theine rechecks the key first when updating the policy, but this behavior might be flagged by the race detector. Starting from v0.6.0, Theine introduced a new option called `UseEntryPool`, which defaults to `false`. If you are dealing with heavy concurrent writes and minimize allocations is crucial, you can enable this option.

**API Details**

simple cache:

```GO
import "github.com/Yiling-J/theine-go"

// key type string, value type string, max size 1000
// max size is the only required configuration to build a client
client, err := theine.NewBuilder[string, string](1000).Build()
if err != nil {
	panic(err)
}

// builder also provide several optional configurations
// you can chain them together and call build once
// client, err := theine.NewBuilder[string, string](1000).Cost(...).Doorkeeper(...).Build()

// or create builder first
builder := theine.NewBuilder[string, string](1000)

// dynamic cost function based on value
// use 0 in Set will call this function to evaluate cost at runtime
builder.Cost(func(v string) int64 {
		return int64(len(v))
})

// enable entryPool (default false)
builder.UseEntryPool(true)

// doorkeeper (default false)
// doorkeeper will drop Set if they are not in bloomfilter yet
// this can improve write performance, but may lower hit ratio
builder.Doorkeeper(true)

// removal listener, this function will be called when entry is removed
// RemoveReason could be REMOVED/EVICTED/EXPIRED
// REMOVED: remove by API
// EVICTED: evicted by Window-TinyLFU policy
// EXPIRED: expired by timing wheel
builder.RemovalListener(func(key K, value V, reason theine.RemoveReason) {})

```
loading cache:

```go
import "github.com/Yiling-J/theine-go"

// loader function: func(ctx context.Context, key K) (theine.Loaded[V], error)
// Loaded struct should include cache value, cost and ttl, which required by Set method
client, err := theine.NewBuilder[string, string](1000).Loading(
	func(ctx context.Context, key string) (theine.Loaded[string], error) {
		return theine.Loaded[string]{Value: key, Cost: 1, TTL: 0}, nil
	},
).Build()
if err != nil {
	panic(err)
}

```
Other builder options are same as simple cache(cost, doorkeeper, removal listener).


**Client API**

```Go
// set, key foo, value bar, cost 1
// success will be false if cost > max size
success := client.Set("foo", "bar", 1)
// cost 0 means using dynamic cost function
// success := client.Set("foo", "bar", 0)

// set with ttl
success = client.SetWithTTL("foo", "bar", 1, 1*time.Second)

// get(simple cache version)
value, ok := client.Get("foo")

// get(loading cache version)
value, err := client.Get(ctx, "foo")

// remove
client.Delete("foo")

// iterate key/value in cache and apply custom function
// if function returns false, range stops the iteration
client.Range(func(key, value int) bool {
	return true
})

// returns an estimation of the cache size usage
client.EstimatedSize()

// get cache stats(in-memory cache only), include hits, misses and hit ratio
client.Stats()

// close client, set hashmaps in shard to nil and close all goroutines
client.Close()

```

## Cache Persistence
Theine supports persisting the cache into `io.Writer` and restoring from `io.Reader`. [Gob](https://pkg.go.dev/encoding/gob) is used to encode/decode data, so **make sure your key/value can be encoded by gob correctly first** before using this feature.

#### API
```go
func (c *Cache[K, V]) SaveCache(version uint64, writer io.Writer) error
func (c *Cache[K, V]) LoadCache(version uint64, reader io.Reader) error
```
**- Important:** please `LoadCache` immediately after client created, or existing entries' TTL might be affected.

#### Example:
```go
// save
f, err := os.Create("test")
err := client.SaveCache(0, f)
f.Close()

// load
f, err = os.Open("test")
require.Nil(t, err)
newClient, err := theine.NewBuilder[int, int](100).Build()
// load immediately after client created
err = newClient.LoadCache(0, f)
f.Close()
```
Version number must be same when saving and loading, or `LoadCache` will return `theine.VersionMismatch` error. You can change the version number when you want to ignore persisted cache.
```go
err := newClient.LoadCache(1, f)
// VersionMismatch is a global variable
if err == theine.VersionMismatch {
	// ignore and skip loading
} else if err != nil {
	// panic error
}
```

Theine does not guarantee that caches from previous versions will be compatible after an upgrade, so it is highly recommended not to use the old persistence file when upgrading Theine.

#### Details
When persisting cache, Theine roughly do:
- Store version number.
- Store clock(used in TTL).
- Store frequency sketch.
- Store entries one by one in protected LRU in most-recently:least-recently order.
- Store entries one by one in probation LRU in most-recently:least-recently order.
- Loop shards and store entries one by one in each shard deque.

When loading cache, Theine roughly do:
- Load version number, compare to current version number.
- Load clock.
- Load frequency sketch.
- Load protected LRU and insert entries back to new protected LRU and shards/timingwheel, expired entries will be ignored. Because cache capacity may change, this step will stop if max protected LRU size reached.
- Load probation LRU and insert entries back to new probation LRU and shards/timingwheel, expired entries will be ignored, Because cache capacity may change, this step will stop if max probation LRU size reached.
- Load deque entries and insert back to shards, expired entries will be ignored.

Theine will save checksum when persisting cache and verify checksum first when loading.

## Benchmarks

Source: https://github.com/maypok86/benchmarks

### throughput

100% read (cpu 8/16/32)

```
goos: linux
goarch: amd64
pkg: github.com/maypok86/benchmarks/throughput
cpu: Intel(R) Xeon(R) Platinum 8163 CPU @ 2.50GHz

BenchmarkCache/zipf_otter_reads=100%,writes=0%-8                88954334                14.78 ns/op       67648151 ops/s
BenchmarkCache/zipf_theine_reads=100%,writes=0%-8               51908306                21.87 ns/op       45729075 ops/s
BenchmarkCache/zipf_ristretto_reads=100%,writes=0%-8            27217994                42.36 ns/op       23606992 ops/s

BenchmarkCache/zipf_otter_reads=100%,writes=0%-16               132372591                8.397 ns/op     119086508 ops/s
BenchmarkCache/zipf_theine_reads=100%,writes=0%-16              85420364                13.78 ns/op       72549558 ops/s
BenchmarkCache/zipf_ristretto_reads=100%,writes=0%-16           47790158                25.17 ns/op       39734070 ops/s

BenchmarkCache/zipf_otter_reads=100%,writes=0%-32               174121321                7.078 ns/op     141273879 ops/s
BenchmarkCache/zipf_theine_reads=100%,writes=0%-32              118185849               10.45 ns/op       95703790 ops/s
BenchmarkCache/zipf_ristretto_reads=100%,writes=0%-32           66458452                18.85 ns/op       53055079 ops/s

```

75% read (cpu 8/16/32)
```
goos: linux
goarch: amd64
pkg: github.com/maypok86/benchmarks/throughput
cpu: Intel(R) Xeon(R) Platinum 8163 CPU @ 2.50GHz

BenchmarkCache/zipf_otter_reads=75%,writes=25%-8                49907841                32.67 ns/op       30609572 ops/s
BenchmarkCache/zipf_theine_reads=75%,writes=25%-8               21484245                48.89 ns/op       20453469 ops/s
BenchmarkCache/zipf_ristretto_reads=75%,writes=25%-8             8651056               130.5 ns/op         7664450 ops/s

BenchmarkCache/zipf_otter_reads=75%,writes=25%-16               50226466                21.85 ns/op       45764160 ops/s
BenchmarkCache/zipf_theine_reads=75%,writes=25%-16              46674459                24.68 ns/op       40523215 ops/s
BenchmarkCache/zipf_ristretto_reads=75%,writes=25%-16           10233784               108.0 ns/op         9262524 ops/s

BenchmarkCache/zipf_otter_reads=75%,writes=25%-32               89651678                11.96 ns/op       83606257 ops/s
BenchmarkCache/zipf_theine_reads=75%,writes=25%-32              75969892                15.53 ns/op       64394679 ops/s
BenchmarkCache/zipf_ristretto_reads=75%,writes=25%-32           15766912                76.37 ns/op       13093551 ops/s

```


100% write (cpu 8/16/32)

```
goos: linux
goarch: amd64
pkg: github.com/maypok86/benchmarks/throughput
cpu: Intel(R) Xeon(R) Platinum 8163 CPU @ 2.50GHz

BenchmarkCache/zipf_otter_reads=0%,writes=100%-8                 1567917               723.0 ns/op         1383080 ops/s
BenchmarkCache/zipf_theine_reads=0%,writes=100%-8                2194747               542.4 ns/op         1843615 ops/s
BenchmarkCache/zipf_ristretto_reads=0%,writes=100%-8             1839237               642.5 ns/op         1556503 ops/s

BenchmarkCache/zipf_otter_reads=0%,writes=100%-16                1384345               846.0 ns/op         1181980 ops/s
BenchmarkCache/zipf_theine_reads=0%,writes=100%-16               1915946               528.8 ns/op         1891008 ops/s
BenchmarkCache/zipf_ristretto_reads=0%,writes=100%-16            1765465               697.3 ns/op         1434089 ops/s

BenchmarkCache/zipf_otter_reads=0%,writes=100%-32                1265883               979.8 ns/op         1020607 ops/s
BenchmarkCache/zipf_theine_reads=0%,writes=100%-32               1953358               526.1 ns/op         1900935 ops/s
BenchmarkCache/zipf_ristretto_reads=0%,writes=100%-32            1618098               696.1 ns/op         1436625 ops/s
```

benchmem 100% write (cpu 32)
```
goos: linux
goarch: amd64
pkg: github.com/maypok86/benchmarks/throughput
cpu: Intel(R) Xeon(R) Platinum 8163 CPU @ 2.50GHz

BenchmarkCache/zipf_otter_reads=0%,writes=100%-32                80 B/op          1 allocs/op
BenchmarkCache/zipf_theine_reads=0%,writes=100%-32               0 B/op           0 allocs/op
BenchmarkCache/zipf_ristretto_reads=0%,writes=100%-32            112 B/op         3 allocs/op

```

### hit ratios

**zipf**

![hit ratios](benchmarks/results/zipf.png)
**s3**

![hit ratios](benchmarks/results/s3.png)
**ds1**

![hit ratios](benchmarks/results/ds1.png)
**oltp**

![hit ratios](benchmarks/results/oltp.png)
**wiki CDN**

![hit ratios](benchmarks/results/wikicdn.png)
**Twitter Cache**

![hit ratios](benchmarks/results/twitter-c52s10.png)


## Secondary Cache(Experimental)

SecondaryCache is the interface for caching data on a secondary tier, which can be a non-volatile media or alternate forms of caching such as sqlite. The purpose of the secondary cache is to support other ways of caching the object. It can be viewed as an extension of Theine’s current in-memory cache.

Currently, the SecondaryCache interface has one implementation inspired by CacheLib's Hybrid Cache.

```go
type SecondaryCache[K comparable, V any] interface {
	Get(key K) (value V, cost int64, expire int64, ok bool, err error)
	Set(key K, value V, cost int64, expire int64) error
	Delete(key K) error
	HandleAsyncError(err error)
}
```

If you plan to use a remote cache or database, such as Redis, as a secondary cache, keep in mind that the in-memory cache remains the primary source of truth. Evicted entries from memory are sent to the secondary cache. This approach differs from most tiered cache systems, where the remote cache is treated as the primary source of truth and is written to first.

#### Secondary Cache Implementations
NVM: https://github.com/Yiling-J/theine-nvm

#### Limitations
- Cache Persistence is not currently supported, but it may be added in the future. You can still use the Persistence API in a hybrid-enabled cache, but only the DRAM part of the cache will be saved or loaded.
- The removal listener will only receive REMOVED events, which are generated when an entry is explicitly removed by calling the Delete API.
- No Range/Len API.


## Support
Feel free to open an issue or ask question in discussions.


theine

<div align="center">
    <h1>~ timedmap ~</h1>
    <strong>A map which has expiring key-value pairs.</strong><br><br>
    <a href="https://pkg.go.dev/github.com/zekroTJA/timedmap"><img src="https://godoc.org/github.com/zekroTJA/timedmap?status.svg" /></a>&nbsp;
    <a href="https://github.com/zekroTJA/timedmap/actions/workflows/main-ci.yml" ><img src="https://github.com/zekroTJA/timedmap/actions/workflows/main-ci.yml/badge.svg" /></a>&nbsp;
    <a href="https://coveralls.io/github/zekroTJA/timedmap"><img src="https://coveralls.io/repos/github/zekroTJA/timedmap/badge.svg" /></a>&nbsp;
    <a href="https://goreportcard.com/report/github.com/zekroTJA/timedmap"><img src="https://goreportcard.com/badge/github.com/zekroTJA/timedmap"/></a>&nbsp;
	<a href="https://github.com/avelino/awesome-go"><img src="https://awesome.re/mentioned-badge.svg"/></a>
<br>
</div>

---

<div align="center">
    <code>go get -u github.com/zekroTJA/timedmap/v2</code>
</div>

---

## Intro

This package allows to set values to a map which will expire and disappear after a specified time.

[Here](https://pkg.go.dev/github.com/zekroTJA/timedmap/v2) you can read the docs of this package, generated by pkg.go.dev.

> [!IMPORTANT]  
> The package has been updated to `v2` which will introduce breaking changes to `v1`.
> - The package now requires a minimum Go version of `v1.19`.
> - `TimedMap` and corresponding constructor function now take type parameters for key and value types for improved type safety.
> - Sections have been removed in favor of performance and simplicity of the package.
> - Previously deprecated functions have been removed.
>
> If you experience issues with `v1`, please create an issue with the specific version mentioned. `v1` will still receive updates for bugs and incosistencies alongside `v2`.

---

## Usage Example

```go
package main

import (
	"log"
	"time"

	"github.com/zekroTJA/timedmap/v2"
)

func main() {

	// Creates a new timed map which scans for
	// expired keys every 1 second
	tm := timedmap.New[string, int](1 * time.Second)

	// Add a key "hey" with the value 213, which should
	// expire after 3 seconds and execute the callback, which
	// prints that the key was expired
	tm.Set("hey", 213, 3*time.Second, func(v int) {
		log.Println("key-value pair of 'hey' has expired")
	})

	// Print key "hey" from timed map
	printKeyVal(tm, "hey")

	// Wait for 5 seconds
	// During this time the main thread is blocked, the
	// key-value pair of "hey" will be expired
	time.Sleep(5 * time.Second)

	// Printing value of key "hey" wil lfail because the
	// key-value pair does not exist anymore
	printKeyVal(tm, "hey")
}

func printKeyVal(tm *timedmap.TimedMap[string, int], key string) {
	d, ok := tm.GetValue(key)
	if !ok {
		log.Println("data expired")
		return
	}

	log.Printf("%v = %d\n", key, d)
}
```

Further examples, you can find in the [examples](examples) directory.

If you want to see this package in a practcal use case scenario, please take a look at the rate limiter implementation of the REST API of [myrunes.com](https://myrunes.com), where I have used `timedmap` for storing client-based limiter instances:  
https://github.com/myrunes/backend/blob/master/internal/ratelimit/ratelimit.go

---

Copyright (c) 2020 zekro Development (Ringo Hoffmann).  
Covered by MIT licence.


timedmap

An in-memory cache with item expiration and generics

## TTLCache - an in-memory cache with item expiration and generics

[![Go Reference](https://pkg.go.dev/badge/github.com/jellydator/ttlcache/v3.svg)](https://pkg.go.dev/github.com/jellydator/ttlcache/v3)
[![Build Status](https://github.com/jellydator/ttlcache/actions/workflows/go.yml/badge.svg)](https://github.com/jellydator/ttlcache/actions/workflows/go.yml)
[![Coverage Status](https://coveralls.io/repos/github/jellydator/ttlcache/badge.svg?branch=master)](https://coveralls.io/github/jellydator/ttlcache?branch=master)
[![Go Report Card](https://goreportcard.com/badge/github.com/jellydator/ttlcache/v3)](https://goreportcard.com/report/github.com/jellydator/ttlcache/v3)

## Features
- Simple API
- Type parameters
- Item expiration and automatic deletion
- Automatic expiration time extension on each `Get` call
- `Loader` interface that may be used to load/lazily initialize missing cache items
- Thread safety
- Event handlers (insertion, update, and eviction)
- Metrics

## Installation
```
go get github.com/jellydator/ttlcache/v3
```

## Usage
The main type of `ttlcache` is `Cache`. It represents a single 
in-memory data store.

To create a new instance of `ttlcache.Cache`, the `ttlcache.New()` function 
should be called:
```go
func main() {
	cache := ttlcache.New[string, string]()
}
```

Note that by default, a new cache instance does not let any of its
items to expire or be automatically deleted. However, this feature
can be activated by passing a few additional options into the 
`ttlcache.New()` function and calling the `cache.Start()` method:
```go
func main() {
	cache := ttlcache.New[string, string](
		ttlcache.WithTTL[string, string](30 * time.Minute),
	)

	go cache.Start() // starts automatic expired item deletion
}
```

Even though the `cache.Start()` method handles expired item deletion well,
there may be times when the system that uses `ttlcache` needs to determine 
when to delete the expired items itself. For example, it may need to 
delete them only when the resource load is at its lowest (e.g., after 
midnight, when the number of users/HTTP requests drops). So, in situations 
like these, instead of calling `cache.Start()`, the system could 
periodically call `cache.DeleteExpired()`:
```go
func main() {
	cache := ttlcache.New[string, string](
		ttlcache.WithTTL[string, string](30 * time.Minute),
	)

	for {
		time.Sleep(4 * time.Hour)
		cache.DeleteExpired()
	}
}
```

The data stored in `ttlcache.Cache` can be retrieved, checked and updated with 
`Set`, `Get`, `Delete`, `Has` etc. methods:
```go
func main() {
	cache := ttlcache.New[string, string](
		ttlcache.WithTTL[string, string](30 * time.Minute),
	)

	// insert data
	cache.Set("first", "value1", ttlcache.DefaultTTL)
	cache.Set("second", "value2", ttlcache.NoTTL)
	cache.Set("third", "value3", ttlcache.DefaultTTL)

	// retrieve data
	item := cache.Get("first")
	fmt.Println(item.Value(), item.ExpiresAt())

	// check key 
	ok := cache.Has("third")
	
	// delete data
	cache.Delete("second")
	cache.DeleteExpired()
	cache.DeleteAll()

	// retrieve data if in cache otherwise insert data
	item, retrieved := cache.GetOrSet("fourth", "value4", WithTTL[string, string](ttlcache.DefaultTTL))

	// retrieve and delete data
	item, present := cache.GetAndDelete("fourth")
}
```

To subscribe to insertion, update and eviction events, `cache.OnInsertion()`, `cache.OnUpdate()` and 
`cache.OnEviction()` methods should be used:
```go
func main() {
	cache := ttlcache.New[string, string](
		ttlcache.WithTTL[string, string](30 * time.Minute),
		ttlcache.WithCapacity[string, string](300),
	)

	cache.OnInsertion(func(ctx context.Context, item *ttlcache.Item[string, string]) {
		fmt.Println(item.Value(), item.ExpiresAt())
	})
	cache.OnUpdate(func(ctx context.Context, item *ttlcache.Item[string, string]) {
		fmt.Println(item.Value(), item.ExpiresAt())
	})
	cache.OnEviction(func(ctx context.Context, reason ttlcache.EvictionReason, item *ttlcache.Item[string, string]) {
		if reason == ttlcache.EvictionReasonCapacityReached {
			fmt.Println(item.Key(), item.Value())
		}
	})

	cache.Set("first", "value1", ttlcache.DefaultTTL)
	cache.DeleteAll()
}
```

To load data when the cache does not have it, a custom or
existing implementation of `ttlcache.Loader` can be used:
```go
func main() {
	loader := ttlcache.LoaderFunc[string, string](
		func(c *ttlcache.Cache[string, string], key string) *ttlcache.Item[string, string] {
			// load from file/make an HTTP request
			item := c.Set("key from file", "value from file")
			return item
		},
	)
	cache := ttlcache.New[string, string](
		ttlcache.WithLoader[string, string](loader),
	)

	item := cache.Get("key from file")
}
```

To restrict the cache's capacity based on criteria beyond the number
of items it can hold, the `ttlcache.WithMaxCost` option allows for
implementing custom strategies. The following example shows how to limit
memory usage for cached entries to ~5KiB.
```go
import (
    "github.com/jellydator/ttlcache"
)

func main() {
    cache := ttlcache.New[string, string](
        ttlcache.WithMaxCost[string, string](5120, func(item ttlcache.CostItem[string, string]) uint64 {
            // Note: The below line doesn't include memory used by internal
            // structures or string metadata for the key and the value.
            return uint64(len(item.Key) + len(item.Value))
        }), 
    )

    cache.Set("first", "value1", ttlcache.DefaultTTL)
}
```

## Examples

See the [example](https://github.com/jellydator/ttlcache/tree/v3/examples) 
directory for applications demonstrating how to use `ttlcache`.


ttlcache

In-memory key:value cache which supports automatic invalidation based on timeouts

# cache2go

[![Latest Release](https://img.shields.io/github/release/muesli/cache2go.svg)](https://github.com/muesli/cache2go/releases)
[![Build Status](https://github.com/muesli/cache2go/workflows/build/badge.svg)](https://github.com/muesli/cache2go/actions)
[![Coverage Status](https://coveralls.io/repos/github/muesli/cache2go/badge.svg?branch=master)](https://coveralls.io/github/muesli/cache2go?branch=master)
[![Go ReportCard](https://goreportcard.com/badge/muesli/cache2go)](https://goreportcard.com/report/muesli/cache2go)
[![GoDoc](https://godoc.org/github.com/golang/gddo?status.svg)](https://pkg.go.dev/github.com/muesli/cache2go)

Concurrency-safe golang caching library with expiration capabilities.

## Installation

Make sure you have a working Go environment (Go 1.2 or higher is required).
See the [install instructions](https://golang.org/doc/install.html).

To install cache2go, simply run:

    go get github.com/muesli/cache2go

To compile it from source:

    cd $GOPATH/src/github.com/muesli/cache2go
    go get -u -v
    go build && go test -v

## Example
```go
package main

import (
	"github.com/muesli/cache2go"
	"fmt"
	"time"
)

// Keys & values in cache2go can be of arbitrary types, e.g. a struct.
type myStruct struct {
	text     string
	moreData []byte
}

func main() {
	// Accessing a new cache table for the first time will create it.
	cache := cache2go.Cache("myCache")

	// We will put a new item in the cache. It will expire after
	// not being accessed via Value(key) for more than 5 seconds.
	val := myStruct{"This is a test!", []byte{}}
	cache.Add("someKey", 5*time.Second, &val)

	// Let's retrieve the item from the cache.
	res, err := cache.Value("someKey")
	if err == nil {
		fmt.Println("Found value in cache:", res.Data().(*myStruct).text)
	} else {
		fmt.Println("Error retrieving value from cache:", err)
	}

	// Wait for the item to expire in cache.
	time.Sleep(6 * time.Second)
	res, err = cache.Value("someKey")
	if err != nil {
		fmt.Println("Item is not cached (anymore).")
	}

	// Add another item that never expires.
	cache.Add("someKey", 0, &val)

	// cache2go supports a few handy callbacks and loading mechanisms.
	cache.SetAboutToDeleteItemCallback(func(e *cache2go.CacheItem) {
		fmt.Println("Deleting:", e.Key(), e.Data().(*myStruct).text, e.CreatedOn())
	})

	// Remove the item from the cache.
	cache.Delete("someKey")

	// And wipe the entire cache table.
	cache.Flush()
}
```

To run this example, go to examples/mycachedapp/ and run:

    go run mycachedapp.go

You can find a [few more examples here](https://github.com/muesli/cache2go/tree/master/examples).
Also see our test-cases in cache_test.go for further working examples.


cache2go

Golang Cache component for multiple drivers

# Cachego

[![Codecov branch](https://img.shields.io/codecov/c/github/faabiosr/cachego/main.svg?style=flat-square)](https://codecov.io/gh/faabiosr/cachego)
[![GoDoc](https://img.shields.io/badge/godoc-reference-5272B4.svg?style=flat-square)](https://pkg.go.dev/github.com/faabiosr/cachego)
[![Go Report Card](https://goreportcard.com/badge/github.com/faabiosr/cachego?style=flat-square)](https://goreportcard.com/report/github.com/faabiosr/cachego)
[![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://github.com/faabiosr/cachego/blob/main/LICENSE)

Simple interface for caching

## Installation

Cachego requires Go 1.21 or later.

```
go get github.com/faabiosr/cachego
```

## Usage

```go
package main

import (
	"log"
	"time"

	"github.com/faabiosr/cachego/sync"
)

func main() {
	cache := sync.New()

	if err := cache.Save("user_id", "1", 10*time.Second); err != nil {
		log.Fatal(err)
	}

	id, err := cache.Fetch("user_id")
	if err != nil {
		log.Fatal(err)
	}

	log.Printf("user id: %s \n", id)

	keys := cache.FetchMulti([]string{"user_id", "user_name"})

	for k, v := range keys {
		log.Printf("%s: %s\n", k, v)
	}

	if cache.Contains("user_name") {
		cache.Delete("user_name")
	}

	if _, err := cache.Fetch("user_name"); err != nil {
		log.Printf("%v\n", err)
	}

	if err := cache.Flush(); err != nil {
		log.Fatal(err)
	}
}

```

## Supported drivers

- [Bolt](/bolt)
- [Chain](/chain)
- [File](/file)
- [Memcached](/memcached)
- [Mongo](/mongo)
- [Redis](/redis)
- [Sqlite3](/sqlite3)
- [Sync](/sync)


## Documentation

Read the full documentation at [https://pkg.go.dev/github.com/faabiosr/cachego](https://pkg.go.dev/github.com/faabiosr/cachego).

## Development

### Requirements

- Install [docker](https://docs.docker.com/install/)
- Install [docker-compose](https://docs.docker.com/compose/install/)

### Makefile
```sh
// Clean up
$ make clean

//Run tests and generates html coverage file
$ make cover

// Up the docker containers for testing
$ make docker

// Format all go files
$ make fmt

//Run linters
$ make lint

// Run tests
$ make test
```

## License

This project is released under the MIT licence. See [LICENSE](https://github.com/faabiosr/cachego/blob/main/LICENSE) for more details.


cachego

RESTful caching micro-service backed by Couchbase server

Couchcache
==
[![PkgGoDev](https://pkg.go.dev/badge/github.com/codingsince1985/couchcache)](https://pkg.go.dev/github.com/codingsince1985/couchcache)
[![Go Report Card](https://goreportcard.com/badge/codingsince1985/couchcache)](https://goreportcard.com/report/codingsince1985/couchcache)

A caching service developed in Go. It provides REST APIs to access key-value pairs stored in Couchbase.

You may also consider [using couchcache as a mocked service](http://codingsince1985.blogspot.com.au/2015/05/use-caching-service-as-mocked.html) when doing TDD.

To start couchcache
--
Run couchcache with Couchbase server (host and port) and bucket (name and password) information

`./couchcache --host=HOST --port=PORT --bucket=BUCKET --pass=PASS`
#### Example
`./couchcache --host=10.99.107.192 --port=8091 --bucket=cachebucket --pass=c@che1t`
#### Default values
```
host: localhost
port: 8091
bucket: couchcache
pass: password
```
Cache service endpoint
--
`http://HOST:8080/key/KEY`
#### Examples
`http://10.99.107.190:8080/key/customer_555`

`http://10.99.107.190:8080/key/the_service_i_want_to_mock-endpoint_a`, if you're mocking other service's endpoint

### To store a key-value pair
* request
  * send `POST` request to endpoint with data in body
  * optionally set TTL by `?ttl=TTL_IN_SEC`
* response
  * `HTTP 201 Created` if stored
  * `HTTP 400 Bad Request` if key or value is invalid

### To retrieve a key
* request
  * send `GET` request to endpoint
* response
  * `HTTP 200 OK` with data in body
  * `HTTP 404 Not Found` if key doesn't exist
  * `HTTP 400 Bad Request` if key is invalid

### To delete a key
* request
  * send `DELETE` request to endpoint
* response
  * `HTTP 204 No Content` if deleted
  * `HTTP 404 Not Found` is key doesn't exist
  * `HTTP 400 Bad Request` if key is invalid

### To append data for a key
* request
  * send `PUT` request to endpoint with data in body
* response
  * `HTTP 200 OK` if appended
  * `HTTP 404 Not Found` if key doesn't exist
  * `HTTP 400 Bad Request` if key or value is invalid

Limitations
--
* Max key length is 250 bytes
* Max value size is 20 MB

See [Couchbase Limits](https://docs.couchbase.com/server/current/learn/clusters-and-availability/size-limitations.html).

License
==
couchcache is distributed under the terms of the MIT license. See LICENSE for details.


couchcache

A data race free Go ache library with high performance and auto pruge functionality

# gocache (basic go in-memory caching)
[![codecov](https://codecov.io/github/yuseferi/gocache/graph/badge.svg?token=98CX2MN5XF)](https://codecov.io/github/yuseferi/gocache)
[![CodeQL](https://github.com/yuseferi/gocache/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/yuseferi/gocache/actions/workflows/github-code-scanning/codeql)
[![Check & Build](https://github.com/yuseferi/gocache/actions/workflows/ci.yml/badge.svg)](https://github.com/yuseferi/gocache/actions/workflows/ci.yml)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/yuseferi/gocache)

gocache is a data race-free cache implementation in Go, providing efficient caching capabilities for your applications.

#### for V1 you can read [this](https://github.com/yuseferi/gocache/tree/v1) 
### Installation

```shell
  go get -u github.com/yuseferi/gocache/v2
```

### Usage:


```Go
cache := gocache.NewCache[string](time.Minute * 2) // with 2 minutes interval cleaning expired items
cache.Set("key", "value", time.Minute) // set cache 
value, found := cache.Get("key") // retrive cache data 
cache.Delete("key") // delete specific key manually
cache.Clear() // clear all cache items ( purge)
size := cache.Size() // get cache size
```


### Contributing
We strongly believe in open-source ❤️😊. Please feel free to contribute by raising issues and submitting pull requests to make gocache even better!


Released under the [GNU GENERAL PUBLIC LICENSE](LICENSE).






In-memory key value storage with TTL for each record

[![Build Status](https://github.com/cheshir/ttlcache/actions/workflows/go.yml/badge.svg)](https://github.com/cheshir/ttlcache/actions/workflows/go.yml)
[![codecov](https://codecov.io/gh/cheshir/ttlcache/branch/main/graph/badge.svg?token=WsaH2t9dGh)](https://codecov.io/gh/cheshir/ttlcache)
[![Go Report Card](https://goreportcard.com/badge/cheshir/ttlcache)](https://goreportcard.com/report/github.com/cheshir/ttlcache)
[![GoDoc](https://godoc.org/github.com/cheshir/ttlcache?status.svg)](https://godoc.org/github.com/cheshir/ttlcache)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/avelino/awesome-go)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/cheshir/go-mq/blob/master/LICENSE)

# ttlcache

## About

**ttlcache** – is a simple and efficient in-memory key value storage with TTL for each record.

The key is of uint64 type. Library provides wrappers for common types:

* IntKey
* ByteKey
* Int8Key
* Uint8Key
* Int16Key
* Uint16Key
* Int32Key
* Uint32Key
* Int64Key
* Uint64Key
* BytesKey ([]byte)
* StringKey
* AnyKey (interface{})

`AnyKey` is not suitable for _very_ intensive usage. Consider writing your own hash function if your keys are complex types, 
and you faced performance degradation.

## Installation

`go get -u github.com/cheshir/ttlcache`

## Usage

```go
package main

import (
    "github.com/cheshir/ttlcache"
)

const (
    minute = 60 * time.Second
    hour = 60 * minute
)

func main() {
    // How often we need to stop the world and remove outdated records.
    resolution := minute

    cache := ttlcache.New(resolution)
    cache.Set(ttlcache.StringKey("some key"), "value", hour)
    value, ok := cache.Get(ttlcache.StringKey("some key"))
    if !ok {
        // there is no record with key "some key" in the cache. Probably it has been expired.
    }

    fmt.Println(value.(string)) // This is necessary type assertion, because returned value is of interface{} type.
}
```

## Performance

If you're interested in benchmarks you can check them in repository.
Just play with numbers and types and check that library is suitable for your purposes.

`go test -bench=. -benchmem`

For those of us who wants to get some numbers without downloading unknown stuff (MacBook Pro 16"):

```go
BenchmarkCache_Set_100-16           8959221               125 ns/op
BenchmarkCache_Set_1000-16          9177854               123 ns/op
BenchmarkCache_Set_10000-16         9247304               131 ns/op
BenchmarkCache_Get_100-16           50562800              23.9 ns/op
BenchmarkCache_Get_1000-16          47270793              26.9 ns/op
BenchmarkCache_Get_10000-16         42578484              27.7 ns/op

```


The generic version of `GCache`, cache support for expirable Cache, LFU, LRU and ARC

# GCache

![Test](https://github.com/szyhf/go-gcache/workflows/Test/badge.svg)
[![PkgGoDev](https://pkg.go.dev/badge/github.com/szyhf/go-gcache/v2)](https://pkg.go.dev/github.com/szyhf/go-gcache/v2?tab=doc)

Cache library for golang. It supports expirable Cache, LFU, LRU and ARC.

It's the generic version of [bluele/gcache](https://github.com/bluele/gcache).

## Features

* Supports generic.

* Supports expirable Cache, LFU, LRU and ARC.

* Goroutine safe.

* Supports event handlers which evict, purge, and add entry. (Optional)

* Automatically load cache if it doesn't exists. (Optional)

## Install

```
$ go get github.com/szyhf/go-gcache/v2
```

## Example

### Manually set a key-value pair.

```go
package main

import (
	"fmt"

	"github.com/szyhf/go-gcache/v2"
)

func main() {
	gc := gcache.New[string, string](20).
		LRU().
		Build()
	gc.Set("key", "ok")
	value, err := gc.Get("key")
	if err != nil {
		panic(err)
	}
	fmt.Println("Get:", value)
}
```

```
Get: ok
```

### Manually set a key-value pair, with an expiration time.

```go
package main

import (
	"fmt"
	"time"

	"github.com/szyhf/go-gcache/v2"
)

func main() {
	gc := gcache.New[string, string](20).
		LRU().
		Build()
	gc.SetWithExpire("key", "ok", time.Second*10)
	value, _ := gc.Get("key")
	fmt.Println("Get:", value)

	// Wait for value to expire
	time.Sleep(time.Second * 10)

	value, err := gc.Get("key")
	if err != nil {
		panic(err)
	}
	fmt.Println("Get:", value)
}
```

```
Get: ok
// 10 seconds later, new attempt:
panic: ErrKeyNotFound
```


### Automatically load value

```go
package main

import (
	"fmt"

	gcache "github.com/szyhf/go-gcache/v2"
)

func main() {
	gc := gcache.New[string, string](20).
		LRU().
		LoaderFunc(func(key string) (string, error) {
			return "ok", nil
		}).
		Build()
	value, err := gc.Get("key")
	if err != nil {
		panic(err)
	}
	fmt.Println("Get:", value)
}
```

```
Get: ok
```

### Automatically load value with expiration

```go
package main

import (
  "fmt"
  "time"

  "github.com/szyhf/go-gcache/v2"
)

func main() {
  var evictCounter, loaderCounter, purgeCounter int
  gc := gcache.New(20).
    LRU().
    LoaderExpireFunc(func(key any) (any, *time.Duration, error) {
      loaderCounter++
      expire := 1 * time.Second
      return "ok", &expire, nil
    }).
    EvictedFunc(func(key, value any) {
      evictCounter++
      fmt.Println("evicted key:", key)
    }).
    PurgeVisitorFunc(func(key, value any) {
      purgeCounter++
      fmt.Println("purged key:", key)
    }).
    Build()
  value, err := gc.Get("key")
  if err != nil {
    panic(err)
  }
  fmt.Println("Get:", value)
  time.Sleep(1 * time.Second)
  value, err = gc.Get("key")
  if err != nil {
    panic(err)
  }
  fmt.Println("Get:", value)
  gc.Purge()
  if loaderCounter != evictCounter+purgeCounter {
    panic("bad")
  }
}
```

```
Get: ok
evicted key: key
Get: ok
purged key: key
```


## Cache Algorithm

  * Least-Frequently Used (LFU)

  Discards the least frequently used items first.

  ```go
  func main() {
  	// size: 10
  	gc := gcache.New[string, string](10).
  		LFU().
  		Build()
  	gc.Set("key", "value")
  }
  ```

  * Least Recently Used (LRU)

  Discards the least recently used items first.

  ```go
  func main() {
    // size: 10
    gc := gcache.New[string, string](10).
      LRU().
      Build()
    gc.Set("key", "value")
  }
  ```

  * Adaptive Replacement Cache (ARC)

  Constantly balances between LRU and LFU, to improve the combined result.

  detail: http://en.wikipedia.org/wiki/Adaptive_replacement_cache

  ```go
  func main() {
    // size: 10
    gc := gcache.New[string, string](10).
      ARC().
      Build()
    gc.Set("key", "value")
  }
  ```

  * SimpleCache (Default)

  SimpleCache has no clear priority for evict cache. It depends on key-value map order.

  ```go
  func main() {
      // size: 10
      gc := gcache.New[string, string](10).Build()
      gc.Set("key", "value")
      v, err := gc.Get("key")
      if err != nil {
      	panic(err)
      }
      // output: "value"
      fmt.Println(v)
  }
  ```

## Loading Cache

If specified `LoaderFunc`, values are automatically loaded by the cache, and are stored in the cache until either evicted or manually invalidated.

```go
func main() {
	gc := gcache.New[string, string](10).
		LRU().
		LoaderFunc(func(key string) (string, error) {
			return "value", nil
		}).
		Build()
	v, _ := gc.Get("key")
	// output: "value"
	fmt.Println(v)
}
```

GCache coordinates cache fills such that only one load in one process of an entire replicated set of processes populates the cache, then multiplexes the loaded value to all callers.

## Expirable cache

```go
func main() {
	// LRU cache, size: 10, expiration: after a hour
	gc := gcache.New[int, int](10).
		LRU().
		Expiration(time.Hour).
		Build()
	for i := 0; i < 3; i++ {
		gc.Set(i, i*i)
	}
}
```

## Event handlers

### Evicted handler

Event handler for evict the entry.

```go
func main() {
	gc := gcache.New[int, int](2).
		EvictedFunc(func(key, value int) {
			fmt.Println("evicted key:", key)
		}).
		Build()
	for i := 0; i < 3; i++ {
		gc.Set(i, i*i)
	}
}
```

```
evicted key: 0
```

### Added handler

Event handler for add the entry.

```go
func main() {
	gc := gcache.New[int, int](2).
		AddedFunc(func(key, value int) {
			fmt.Println("added key:", key)
		}).
		Build()
	for i := 0; i < 3; i++ {
		gc.Set(i, i*i)
	}
}
```

```
added key: 0
added key: 1
added key: 2
```

# Origin Author

**Jun Kimura**

* <http://github.com/bluele>
* <junkxdev@gmail.com>


go-gcache

Fast in-memory key:value store/cache library. Pointer caches

# go-mcache

[![Go Report Card](https://goreportcard.com/badge/github.com/OrlovEvgeny/go-mcache)](https://goreportcard.com/report/github.com/OrlovEvgeny/go-mcache)
[![GoDoc](https://pkg.go.dev/badge/github.com/OrlovEvgeny/go-mcache)](https://pkg.go.dev/github.com/OrlovEvgeny/go-mcache)
[![Tests](https://github.com/OrlovEvgeny/go-mcache/actions/workflows/test.yml/badge.svg)](https://github.com/OrlovEvgeny/go-mcache/actions/workflows/test.yml)
[![Release](https://img.shields.io/github/v/release/OrlovEvgeny/go-mcache)](https://github.com/OrlovEvgeny/go-mcache/releases/latest)

Generic in-memory cache for Go with TinyLFU admission, sharded storage, and lock-free read path.

## Design

mcache combines two ideas to achieve both high hit ratios and high throughput:

**Admission control via TinyLFU.** Not every new item gets into the cache. On insertion, a Count-Min Sketch estimates the access frequency of the incoming item and compares it against a random sample of existing entries (SampledLFU). If the new item has lower frequency, it is rejected. This prevents one-time keys from evicting frequently accessed data — a problem that LRU caches have by design. The frequency sketch uses 4-bit counters (8 bytes per ~16 tracked keys) and resets periodically to adapt to changing access patterns.

**Lock-free read path.** The TinyLFU frequency tracking (Count-Min Sketch + Bloom filter doorkeeper) is implemented with atomic operations — no mutexes on reads. The storage layer uses 1024 shards with per-shard `sync.RWMutex` and cache-line padding between shards to eliminate false sharing. As a result, read throughput scales linearly with cores.

### Architecture

```
Cache[K, V]
├── ShardedStore         1024 shards, cache-line padded, per-shard RWMutex
│   └── map[K]*Entry     standard Go map per shard
├── Policy[K]            generic over key type (no hash-collision ambiguity)
│   ├── TinyLFU          doorkeeper (Bloom filter) + Count-Min Sketch
│   └── SampledLFU[K]    dense array + map for O(1) random sampling
├── ExpiryHeap           min-heap for TTL-based expiration, O(log n) ops
├── RadixTree            opt-in, for prefix search on string keys
├── WriteBuffer          lock-free ring buffer for async batching
└── Metrics              atomic counters, zero-cost when not read
```

### Why exact-key policy matters

The policy tracks entries by exact key `K`, not by hash. This means:
- No hash collision ambiguity — two keys with the same hash are tracked independently
- Eviction victims are returned as `{Key, KeyHash}` pairs — no reverse lookup needed
- The `SampledLFU` uses a dense array with swap-delete, so random sampling is `O(sampleSize)` instead of `O(n)` map iteration

### Expiration

Entries with TTL are tracked in a min-heap. A background goroutine sweeps expired entries once per second using a shard-local collect-and-delete: each shard is locked once for the entire sweep, expired entries are removed in bulk, and policy/radix/callback updates happen outside the shard lock.

## Install

```
go get github.com/OrlovEvgeny/go-mcache
```

Requires Go 1.23+

## Usage

```go
cache := mcache.NewCache[string, int](
    mcache.WithMaxEntries[string, int](100_000),
)
defer cache.Close()

cache.Set("key", 42, 5*time.Minute)

val, ok := cache.Get("key")  // type-safe, no assertion
```

### Cost-based eviction

```go
cache := mcache.NewCache[string, []byte](
    mcache.WithMaxCost[string, []byte](100 << 20), // 100 MB
    mcache.WithCostFunc[string, []byte](func(v []byte) int64 {
        return int64(len(v))
    }),
)

// A 10 MB value may evict multiple smaller entries
cache.Set("large", make([]byte, 10<<20), 0)
```

### Batch reads

```go
batch := cache.GetBatchOptimized(keys)
// Keys are sorted by shard index before lookup
// for sequential memory access and reduced lock contention
for i, key := range batch.Keys {
    if batch.Found[i] {
        process(key, batch.Values[i])
    }
}
```

### Prefix search (string keys, opt-in)

```go
cache := mcache.NewCache[string, int](
    mcache.WithPrefixSearch[string, int](true),
)

cache.Set("user:1:name", 1, 0)
cache.Set("user:1:email", 2, 0)
cache.Set("user:2:name", 3, 0)

iter := cache.ScanPrefix("user:1:", 0, 100)
for iter.Next() {
    fmt.Println(iter.Key()) // user:1:name, user:1:email
}
```

### Async writes

```go
cache := mcache.NewCache[string, int](
    mcache.WithBufferItems[string, int](64),
)

cache.Set("key", 1, 0)    // buffered, returns immediately
cache.Wait()               // blocks until buffer is flushed
val, _ := cache.Get("key") // guaranteed to see the value
```

When the write buffer is full, the operation falls back to synchronous execution instead of dropping the entry.

## Configuration

| Option | Description | Default |
|--------|-------------|---------|
| `WithMaxEntries` | Maximum number of entries | unlimited |
| `WithMaxCost` | Maximum total cost | unlimited |
| `WithNumCounters` | TinyLFU counters (recommend 10x max entries) | auto |
| `WithShardCount` | Number of shards (power of 2) | 1024 |
| `WithBufferItems` | Async write buffer size (0 = sync) | 0 |
| `WithDefaultTTL` | Default TTL for entries without explicit TTL | 0 (no expiry) |
| `WithCostFunc` | Custom cost calculator | cost = 1 |
| `WithKeyHasher` | Custom key hash function | auto (FNV-1a) |
| `WithLockFreePolicy` | Use lock-free TinyLFU for reads | true |
| `WithPrefixSearch` | Enable radix tree for ScanPrefix | false |
| `WithOnEvict` | Callback on eviction | nil |
| `WithOnExpire` | Callback on TTL expiration | nil |
| `WithOnReject` | Callback when TinyLFU rejects entry | nil |

### Supported key types

Built-in zero-allocation hashing for: `string`, `int`, `int8`–`int64`, `uint`–`uint64`, `float32`, `float64`, `bool`, `uintptr`. Other `comparable` types use `fmt.Sprintf` fallback — provide `WithKeyHasher` for production use with custom types.

## API

```go
// Core
cache.Set(key K, value V, ttl time.Duration) bool
cache.SetWithCost(key K, value V, cost int64, ttl time.Duration) bool
cache.Get(key K) (V, bool)
cache.Has(key K) bool
cache.Delete(key K) bool
cache.Len() int
cache.Clear()
cache.Close()
cache.Wait()

// Batch
cache.GetMany(keys []K) map[K]V
cache.GetBatch(keys []K) *BatchResult[K, V]
cache.GetBatchOptimized(keys []K) *BatchResult[K, V]
cache.SetMany(items []Item[K, V]) int
cache.DeleteMany(keys []K) int

// Iterators (cursor-based, Redis-style)
cache.Scan(cursor uint64, count int) *Iterator[K, V]
cache.ScanPrefix(prefix string, cursor uint64, count int) *Iterator[K, V]
cache.ScanMatch(pattern string, cursor uint64, count int) *Iterator[K, V]

// Iterator methods
iter.Next() bool
iter.Key() K
iter.Value() V
iter.All() []Item[K, V]
iter.Keys() []K
iter.ForEach(func(K, V) bool)
iter.Count() int
iter.Cursor() uint64
iter.Close()

// Metrics
cache.Metrics() MetricsSnapshot
// Fields: Hits, Misses, HitRatio, Sets, Deletes, Evictions,
//         Expirations, Rejections, CostAdded, CostEvicted, BufferDrops
```

## Benchmarks

Apple M4 Pro, Go 1.23. Run with `go test -bench=. -benchmem`.

```
BenchmarkCacheGet                  4,915,591     445.9 ns/op     0 B/op    0 allocs/op
BenchmarkCacheSet                  2,185,386    1061   ns/op    49 B/op    1 allocs/op
BenchmarkCacheSetWithTTL           2,511,756     973.9 ns/op    49 B/op    1 allocs/op
BenchmarkCacheMixed                4,878,026     473.3 ns/op     9 B/op    0 allocs/op
BenchmarkCacheHas                137,653,788      17.5 ns/op     0 B/op    0 allocs/op
BenchmarkCacheOperations/Read     40,523,341      58.0 ns/op     5 B/op    0 allocs/op
BenchmarkCacheZipf                   683,647    3624   ns/op    13 B/op    0 allocs/op
```

`CacheGet` includes TinyLFU frequency tracking on every access. `CacheHas` is a pure shard lookup without policy update. The difference (~17 ns vs ~446 ns) shows the cost of the admission policy — which is the tradeoff for better hit ratios on skewed workloads (`CacheZipf` achieves 87.4% hit rate).

Lock-free internals:

```
BenchmarkCMSketchLockFreeIncrement            58,410,620    20.8 ns/op    0 B/op
BenchmarkCMSketchLockFreeIncrementParallel    43,926,879    24.5 ns/op    0 B/op
BenchmarkBloomFilterLockFreeAddParallel      889,117,638     1.3 ns/op    0 B/op
BenchmarkPolicyLockFreeAccess                 35,165,865    36.3 ns/op    0 B/op
```

Parallel CM Sketch throughput degrades only ~18% from single-goroutine, showing the lock-free design scales under contention.

## Thread safety

All operations are safe for concurrent use. The concurrency model:

- **Reads**: shard RLock + lock-free TinyLFU access → no global contention
- **Writes**: shard Lock + policy mutex (held only during eviction decision)
- **Expiration**: shard-local sweep under write lock, policy/callback updates outside lock
- **Metrics**: atomic counters, no locks
- **Shards**: cache-line padded to prevent false sharing between cores

## Legacy API

The `mcache.New()` / `CacheDriver` API from v1 still works. It uses `safeMap` + GC-based expiration without TinyLFU. See `mcache.go` and `gcmap/` for details. For new code, use the generic `NewCache[K, V]` API.

## License

MIT


go-mcache

Unified Go cache library supporting multi-level caching

# jetcache-go

![banner](docs/images/banner.png)

<p>
<a href="https://github.com/mgtv-tech/jetcache-go/actions"><img src="https://github.com/mgtv-tech/jetcache-go/workflows/Go/badge.svg" alt="Build Status"></a>
<a href="https://codecov.io/gh/mgtv-tech/jetcache-go"><img src="https://codecov.io/gh/mgtv-tech/jetcache-go/master/graph/badge.svg" alt="codeCov"></a>
<a href="https://goreportcard.com/report/github.com/mgtv-tech/jetcache-go"><img src="https://goreportcard.com/badge/github.com/mgtv-tech/jetcache-go" alt="Go Report Card"></a>
<a href="https://github.com/mgtv-tech/jetcache-go/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
<a href="https://github.com/mgtv-tech/jetcache-go/releases"><img src="https://img.shields.io/github/release/mgtv-tech/jetcache-go" alt="Release"></a>
</p>

Language: [简体中文](README_zh.md)

## Overview

`jetcache-go` is a production-grade cache framework for Go. It is inspired by Java JetCache and extends the `go-redis/cache` model with two-level caching, singleflight-based miss protection, typed batch APIs, and operational features for large-scale services.

## Why jetcache-go

- Two-level cache: local (`FreeCache`/`TinyLFU`) + remote (`Redis`)
- Singleflight miss collapse and optional auto-refresh
- Generic `MGet` with pipeline optimization
- Cache penetration protection via not-found placeholder strategy
- Built-in stats and Prometheus plugin integration
- Interface-driven design for local/remote/codec/stats extensions

## Feature Availability

- Generic `MGet` + load callback + pipeline optimization: `v1.1.0+`
- Cross-process local cache invalidation after updates: `v1.1.1+`

See [Versioning](docs/EN/Versioning.md) for details.

## Quick Start

Install:

```bash
go get github.com/mgtv-tech/jetcache-go
```

Minimal usage:

```go
package main

import (
	"context"
	"time"

	cache "github.com/mgtv-tech/jetcache-go"
	"github.com/mgtv-tech/jetcache-go/local"
	"github.com/mgtv-tech/jetcache-go/remote"
	"github.com/redis/go-redis/v9"
)

func main() {
	rdb := redis.NewClient(&redis.Options{Addr: "127.0.0.1:6379"})
	c := cache.New(
		cache.WithName("user-cache"),
		cache.WithLocal(local.NewTinyLFU(100_000, time.Minute)),
		cache.WithRemote(remote.NewGoRedisV9Adapter(rdb)),
	)
	defer c.Close()

	var user string
	_ = c.Once(context.Background(), "user:1001",
		cache.Value(&user),
		cache.Do(func(context.Context) (any, error) {
			return "alice", nil
		}),
	)
}
```

See full quick start and scenarios:

- [Quick Start](docs/EN/QuickStart.md)
- [Examples](docs/EN/Examples/README.md)

## Documentation

Getting started:

- [Quick Start](docs/EN/QuickStart.md)
- [Architecture](docs/EN/Architecture.md)
- [Examples](docs/EN/Examples/README.md)

Configuration and API:

- [Configuration](docs/EN/Config.md)
- [API Reference](docs/EN/CacheAPI.md)
- [Versioning](docs/EN/Versioning.md)
- [Terminology](docs/EN/Terminology.md)
- [Embedded Components](docs/EN/Embedded.md)
- [Plugin Ecosystem](docs/EN/Plugin.md)

Production operations:

- [Best Practices](docs/EN/BestPractices.md)
- [Monitoring](docs/EN/Monitoring.md)
- [Troubleshooting](docs/EN/Troubleshooting.md)
- [FAQ](docs/EN/FAQ.md)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT. See [LICENSE](LICENSE).

## Contact

- Email: `daoshenzzg@gmail.com`
- Issues: <https://github.com/mgtv-tech/jetcache-go/issues>


jetcache-go

Pocache is a minimal cache package which focuses on a preemptive optimistic caching strategy

<p align="center"><img src="https://github.com/user-attachments/assets/1038467d-6058-4227-8a59-cf29b847fb2b" alt="pocache gopher" width="256px"/></p>

[![](https://github.com/naughtygopher/pocache/actions/workflows/go.yml/badge.svg?branch=main)](https://github.com/naughtygopher/pocache/actions)
[![Go Reference](https://pkg.go.dev/badge/github.com/naughtygopher/pocache.svg)](https://pkg.go.dev/github.com/naughtygopher/pocache)
[![Go Report Card](https://goreportcard.com/badge/github.com/naughtygopher/pocache?cache_invalidate=v0.3.0)](https://goreportcard.com/report/github.com/naughtygopher/pocache)
[![Coverage Status](https://coveralls.io/repos/github/naughtygopher/pocache/badge.svg?branch=main&cache_invalidate=v0.3.0)](https://coveralls.io/github/naughtygopher/pocache?branch=main)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/creativecreature/sturdyc/blob/master/LICENSE)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go?tab=readme-ov-file#caches)

# Pocache

Pocache (`poh-cash (/poʊ kæʃ/)`), **P**reemptive **o**ptimistic cache, is a lightweight in-app caching package. It introduces preemptive cache updates, optimizing performance in concurrent environments by reducing redundant database calls while maintaining fresh data. It uses [Hashicorp's Go LRU package](https://github.com/hashicorp/golang-lru) as the default storage.

Yet another _elegant_ solution for the infamous [Thundering herd problem](https://en.wikipedia.org/wiki/Thundering_herd_problem), save your database(s)!

## Key Features

1. **Preemptive Cache Updates:** Automatically updates cache entries _nearing_ expiration.
2. **Threshold Window:** Configurable time window before cache expiration to trigger updates.
3. **Serve stale**: Opt-in configuration to serve expired cache and do a background refresh.
4. **Debounced Updates:** Prevents excessive I/O calls by debouncing concurrent update requests for the same key.
5. **Custom store**: customizable underlying storage to extend/replace in-app cache or use external cache database.

## Why use Pocache?

In highly concurrent environments (e.g., web servers), multiple requests try to access the same cache entry simultaneously. Without query call suppression / call debouncing, the app would query the underlying database multiple times until the cache is refreshed. While trying to solve the thundering herd problem, most applications serve stale/expired cache until the update is completed.

Pocache solves these scenarios by combining debounce mechanism along with optimistic updates during the threshold window, keeping the cache up to date all the time and never having to serve stale cache!

## How does it work?

Given a cache expiration time and a threshold window, Pocache triggers a preemptive cache update when a value is accessed within the threshold window.

Example:

-   Cache expiration: 10 minutes
-   Threshold window: 1 minute

```
|______________________ ____threshold window__________ ______________|
0 min                   9 mins                         10 mins
Add key here            Get key within window          Key expires
```

When a key is fetched within the threshold window (between 9-10 minutes), Pocache initiates a background update for that key (_preemptive_). This ensures fresh data availability, anticipating future usage (_optimistic_).

## Custom store

Pocache defines the following interface for its underlying storage. You can configure storage of your choice as long as it implements this simple interface, and is provided as a configuration.

```golang
type store[K comparable, T any] interface {
	Add(key K, value *Payload[T]) (evicted bool)
	Get(key K) (value *Payload[T], found bool)
	Remove(key K) (present bool)
}
```

Below is an example(not for production use) of setting a custom store.

```golang
type mystore[Key comparable, T any] struct{
    data sync.Map
}

func (ms *mystore[K,T]) Add(key K, value *Payload[T]) (evicted bool) {
    ms.data.Store(key, value)
}

func (ms *mystore[K,T]) Get(key K) (value *Payload[T], found bool) {
    v, found  := ms.data.Load(key)
    if !found {
        return nil, found
    }

    value, _ := v.(*Payload[T])
    return value, true
}

func (ms *mystore[K,T]) Remove(key K) (present bool) {
    _, found  := ms.data.Load(key)
    ms.data.Delete(key)
    return found
}

func foo() {
    cache, err := pocache.New(pocache.Config[string, string]{
        Store: mystore{data: sync.Map{}}
	})
}
```

## Full example

```golang
package main

import (
	"context"
	"fmt"
	"time"

	"github.com/naughtygopher/pocache"
)

type Item struct {
	ID          string
	Name        string
	Description string
}

func newItem(key string) *Item {
	return &Item{
		ID:          fmt.Sprintf("%d", time.Now().Nanosecond()),
		Name:        "name::" + key,
		Description: "description::" + key,
	}
}

func updater(ctx context.Context, key string) (*Item, error) {
	return newItem(key), nil
}

func onErr(err error) {
	panic(fmt.Sprintf("this should never have happened!: %+v", err))
}

func main() {
	cache, err := pocache.New(pocache.Config[string, *Item]{
		// LRUCacheSize is the number of keys to be maintained in the cache (Optional, default 1000)
		LRUCacheSize: 100000,
		// QLength is the length of update and delete queue (Optional, default 1000)
		QLength: 1000,

		// CacheAge is for how long the cache would be maintained, apart from the LRU eviction
		// It's maintained to not maintain stale data if/when keys are not evicted based on LRU
		// (Optional, default 1minute)
		CacheAge: time.Hour,
		// Threshold is the duration prior to expiry, when the key is considered eligible to be updated
		// (Optional, default 1 second)
		Threshold: time.Minute * 5,

		// ServeStale will not return error if the cache has expired. It will return the stale
		// value, and trigger an update as well. This is useful for usecases where it's ok
		// to serve stale values and data consistency is not of paramount importance.
		// (Optional, default false)
		ServeStale: false,

		// UpdaterTimeout is the context time out for when the updater function is called
		// (Optional, default 1 second)
		UpdaterTimeout: time.Second * 15,
		// Updater is optional, but without it it's a basic LRU cache
		Updater: updater,

		// ErrWatcher is called when there's any error when trying to update cache (Optional)
		ErrWatcher: onErr,
	})
	if err != nil {
		panic(err)
	}

	const key = "hello"
	item := newItem(key)
	e := cache.Add(key, item)
	fmt.Println("evicted:", e)

	ee := cache.BulkAdd([]pocache.Tuple[string, *Item]{
		{Key: key + "2", Value: newItem(key + "2")},
	})
	fmt.Println("evicted list:", ee)

	ii := cache.Get(key)
	if ii.Found {
		fmt.Println("value:", ii.V)
	}

	ii = cache.Get(key + "2")
	if ii.Found {
		fmt.Println("value:", ii.V)
	}
}
```

## The gopher

The gopher used here was created using [Gopherize.me](https://gopherize.me/). Pocache helps you to stop the herd from thundering.


pocache

# Ristretto

[![GitHub License](https://img.shields.io/github/license/dgraph-io/ristretto)](https://github.com/dgraph-io/ristretto?tab=Apache-2.0-1-ov-file#readme)
[![GitHub Repo stars](https://img.shields.io/github/stars/dgraph-io/ristretto)](https://github.com/dgraph-io/ristretto/stargazers)
[![GitHub commit activity](https://img.shields.io/github/commit-activity/m/dgraph-io/ristretto)](https://github.com/dgraph-io/ristretto/commits/main/)
[![Go Report Card](https://img.shields.io/badge/go%20report-A%2B-brightgreen)](https://goreportcard.com/report/github.com/dgraph-io/ristretto)

Ristretto is a fast, concurrent cache library built with a focus on performance and correctness.

The motivation to build Ristretto comes from the need for a contention-free cache in [Dgraph][].

[Dgraph]: https://github.com/dgraph-io/dgraph

## Features

- **High Hit Ratios** - with our unique admission/eviction policy pairing, Ristretto's performance
  is best in class.
  - **Eviction: SampledLFU** - on par with exact LRU and better performance on Search and Database
    traces.
  - **Admission: TinyLFU** - extra performance with little memory overhead (12 bits per counter).
- **Fast Throughput** - we use a variety of techniques for managing contention and the result is
  excellent throughput.
- **Cost-Based Eviction** - any large new item deemed valuable can evict multiple smaller items
  (cost could be anything).
- **Fully Concurrent** - you can use as many goroutines as you want with little throughput
  degradation.
- **Metrics** - optional performance metrics for throughput, hit ratios, and other stats.
- **Simple API** - just figure out your ideal `Config` values and you're off and running.

## Status

Ristretto is production-ready. See [Projects using Ristretto](#projects-using-ristretto).

## Getting Started

### Installing

To start using Ristretto, install Go 1.21 or above. Ristretto needs go modules. From your project,
run the following command

```sh
go get github.com/dgraph-io/ristretto/v2
```

This will retrieve the library.

#### Choosing a version

Following these rules:

- v1.x.x is the first version used in most programs with Ristretto dependencies.
- v2.x.x is the new version with support for generics, for which it has a slightly different
  interface. This version is designed to solve compatibility problems of programs using the old
  version of Ristretto. If you start writing a new program, it is recommended to use this version.

## Usage

```go
package main

import (
  "fmt"

  "github.com/dgraph-io/ristretto/v2"
)

func main() {
  cache, err := ristretto.NewCache(&ristretto.Config[string, string]{
    NumCounters: 1e7,     // number of keys to track frequency of (10M).
    MaxCost:     1 << 30, // maximum cost of cache (1GB).
    BufferItems: 64,      // number of keys per Get buffer.
  })
  if err != nil {
    panic(err)
  }
  defer cache.Close()

  // set a value with a cost of 1
  cache.Set("key", "value", 1)

  // wait for value to pass through buffers
  cache.Wait()

  // get value from cache
  value, found := cache.Get("key")
  if !found {
    panic("missing value")
  }
  fmt.Println(value)

  // del value from cache
  cache.Del("key")
}
```

## Benchmarks

The benchmarks can be found in
https://github.com/dgraph-io/dgraph-benchmarks/tree/main/cachebench/ristretto.

### Hit Ratios for Search

This trace is described as "disk read accesses initiated by a large commercial search engine in
response to various web search requests."

<p align="center">
  <img src="https://raw.githubusercontent.com/dgraph-io/ristretto/main/benchmarks/Hit%20Ratios%20-%20Search%20(ARC-S3).svg"
  alt="Graph showing hit ratios comparison for search workload">
</p>

### Hit Ratio for Database

This trace is described as "a database server running at a commercial site running an ERP
application on top of a commercial database."

<p align="center">
  <img src="https://raw.githubusercontent.com/dgraph-io/ristretto/main/benchmarks/Hit%20Ratios%20-%20Database%20(ARC-DS1).svg"
  alt="Graph showing hit ratios comparison for database workload">
</p>

### Hit Ratio for Looping

This trace demonstrates a looping access pattern.

<p align="center">
  <img src="https://raw.githubusercontent.com/dgraph-io/ristretto/main/benchmarks/Hit%20Ratios%20-%20Glimpse%20(LIRS-GLI).svg"
  alt="Graph showing hit ratios comparison for looping access pattern">
</p>

### Hit Ratio for CODASYL

This trace is described as "references to a CODASYL database for a one hour period."

<p align="center">
  <img src="https://raw.githubusercontent.com/dgraph-io/ristretto/main/benchmarks/Hit%20Ratios%20-%20CODASYL%20(ARC-OLTP).svg"
  alt="Graph showing hit ratios comparison for CODASYL workload">
</p>

### Throughput for Mixed Workload

<p align="center">
  <img src="https://raw.githubusercontent.com/dgraph-io/ristretto/main/benchmarks/Throughput%20-%20Mixed.svg"
  alt="Graph showing throughput comparison for mixed workload">
</p>

### Throughput for Read Workload

<p align="center">
  <img src="https://raw.githubusercontent.com/dgraph-io/ristretto/main/benchmarks/Throughput%20-%20Read%20(Zipfian).svg"
  alt="Graph showing throughput comparison for read workload">
</p>

### Through for Write Workload

<p align="center">
  <img src="https://raw.githubusercontent.com/dgraph-io/ristretto/main/benchmarks/Throughput%20-%20Write%20(Zipfian).svg"
  alt="Graph showing throughput comparison for write workload">
</p>

## Projects Using Ristretto

Below is a list of known projects that use Ristretto:

- [Badger](https://github.com/dgraph-io/badger) - Embeddable key-value DB in Go
- [Dgraph](https://github.com/dgraph-io/dgraph) - Horizontally scalable and distributed GraphQL
  database with a graph backend

## FAQ

### How are you achieving this performance? What shortcuts are you taking?

We go into detail in the
[Ristretto blog post](https://web.archive.org/web/20250806164019/https://hypermode.com/blog/introducing-ristretto-high-perf-go-cache),
but in short: our throughput performance can be attributed to a mix of batching and eventual
consistency. Our hit ratio performance is mostly due to an excellent
[admission policy](https://arxiv.org/abs/1512.00727) and SampledLFU eviction policy.

As for "shortcuts," the only thing Ristretto does that could be construed as one is dropping some
Set calls. That means a Set call for a new item (updates are guaranteed) isn't guaranteed to make it
into the cache. The new item could be dropped at two points: when passing through the Set buffer or
when passing through the admission policy. However, this doesn't affect hit ratios much at all as we
expect the most popular items to be Set multiple times and eventually make it in the cache.

### Is Ristretto distributed?

No, it's just like any other Go library that you can import into your project and use in a single
process.


ristretto

A caching library with advanced concurrency features designed to make I/O heavy applications robust and highly performant

The Best Go Libraries For Database - Caches (29)

gdcache

go-cache

bcache

BigCache

clusteredBigCache

coherence-go-client

EchoVault

fastcache

GCache

gocache

groupcache

icache

imcache

nscache

otter

theine

timedmap

ttlcache

cache2go

cachego

couchcache

gocache

ttlcache

go-gcache

go-mcache

jetcache-go

pocache

ristretto

sturdyc