gcache

package module
v0.0.0-...-8c7a3a7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 8, 2025 License: MIT Imports: 11 Imported by: 0

README

GCache

GoDoc

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

Features

  • Supports expirable Cache, LFU, LRU and ARC.
  • Auto-renewal cache items. (Optional)
  • Goroutine safe.
  • Supports event handlers which evict, purge, and add entry. (Optional)
  • Automatically load cache if it doesn't exists. (Optional)
  • Supports context.
  • Supports shared cache.
  • Supports generic interface.
  • Supports managed by the Arena allocator. (Optional)

Install

$ go get github.com/limpo1989/gcache

Example

package main

import (
	"context"
	"fmt"

	"github.com/limpo1989/gcache"
)

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

Acknowledgement

This project initial code based from gcache written by bluele

Documentation

Index

Constants

View Source 
const (
	TypeSimple = "simple"
	TypeLru    = "lru"
	TypeLfu    = "lfu"
	TypeArc    = "arc"
)

Variables

View Source 
var ErrKeyNotFound = errors.New("key not found")

Functions

This section is empty.

Types

type ARC 

type ARC[K comparable, V any] struct {
	// contains filtered or unexported fields
}

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

func (*ARC[K, V]) Clear 

func (c *ARC[K, V]) Clear()

Clear removes all key-value pairs from the cache

func (*ARC[K, V]) Compact 

func (c *ARC[K, V]) Compact() (n int)

Compact clear expired items

func (*ARC[K, V]) Get 

func (c *ARC[K, V]) Get(ctx context.Context, key K) (*V, error)

Get a value from cache pool using key if it exists. If not exists and it has LoaderFunc, it will generate the value using you have specified LoaderFunc method returns value.

func (*ARC[K, V]) GetFn 

func (c *ARC[K, V]) GetFn(ctx context.Context, key K, fn func(value *V, err error))

GetFn callbacks the value for the specified key if it is present in the cache. If the key is not present in the cache and the cache has LoaderFunc, invoke the `LoaderFunc` function and inserts the key-value pair in the cache. If the key is not present in the cache and the cache does not have a LoaderFunc, Callback ErrKeyNotFound.

func (*ARC[K, V]) GetIfPresent 

func (c *ARC[K, V]) GetIfPresent(ctx context.Context, key K) (*V, error)

GetIfPresent gets a value from cache pool using key if it exists. If it does not exists key, returns ErrKeyNotFound.

func (*ARC[K, V]) GetIfPresentFn 

func (c *ARC[K, V]) GetIfPresentFn(ctx context.Context, key K, fn func(value *V, err error))

GetIfPresentFn callbacks the value for the specified key if it is present in the cache. Callback ErrKeyNotFound if the key is not present.

func (*ARC[K, V]) Has 

func (c *ARC[K, V]) Has(key K) bool

Has checks if key exists in cache

func (*ARC[K, V]) Keys 

func (c *ARC[K, V]) Keys() []K

Keys returns a slice of the keys in the cache.

func (*ARC[K, V]) Len 

func (c *ARC[K, V]) Len() int

Len returns the number of items in the cache.

func (*ARC[K, V]) Remove 

func (c *ARC[K, V]) Remove(key K) bool

Remove removes the provided key from the cache.

func (*ARC[K, V]) Set 

func (c *ARC[K, V]) Set(key K, value *V) error

func (*ARC[K, V]) SetWithExpire 

func (c *ARC[K, V]) SetWithExpire(key K, value *V, expiration time.Duration) error

SetWithExpire a new key-value pair with an expiration time

func (*ARC[K, V]) Touch 

func (c *ARC[K, V]) Touch(ctx context.Context, key K) error

Touch updates the expiration time of an existing key. If the key is not present in the cache and the cache has LoaderFunc, invoke the `LoaderFunc` function and inserts the key-value pair in the cache. If the key is not present in the cache and the cache does not have a LoaderFunc, return ErrKeyNotFound.

type AddedFunc 

type AddedFunc[K comparable, V any] func(K, *V)

type Cache 

type Cache[K comparable, V any] interface {
	// Set inserts or updates the specified key-value pair.
	Set(key K, value *V) error
	// SetWithExpire inserts or updates the specified key-value pair with an expiration time.
	SetWithExpire(key K, value *V, expiration time.Duration) error
	// Get returns the value for the specified key if it is present in the cache.
	// If the key is not present in the cache and the cache has LoaderFunc,
	// invoke the `LoaderFunc` function and inserts the key-value pair in the cache.
	// If the key is not present in the cache and the cache does not have a LoaderFunc,
	// return ErrKeyNotFound.
	Get(ctx context.Context, key K) (*V, error)
	// GetIfPresent returns the value for the specified key if it is present in the cache.
	// Return ErrKeyNotFound if the key is not present.
	GetIfPresent(ctx context.Context, key K) (*V, error)
	// GetFn callbacks the value for the specified key if it is present in the cache.
	// If the key is not present in the cache and the cache has LoaderFunc,
	// invoke the `LoaderFunc` function and inserts the key-value pair in the cache.
	// If the key is not present in the cache and the cache does not have a LoaderFunc,
	// Callback ErrKeyNotFound.
	GetFn(ctx context.Context, key K, fn func(value *V, err error))
	// GetIfPresentFn callbacks the value for the specified key if it is present in the cache.
	// Callback ErrKeyNotFound if the key is not present.
	GetIfPresentFn(ctx context.Context, key K, fn func(value *V, err error))
	// Touch updates the expiration time of an existing key.
	// If the key is not present in the cache and the cache has LoaderFunc,
	// invoke the `LoaderFunc` function and inserts the key-value pair in the cache.
	// If the key is not present in the cache and the cache does not have a LoaderFunc,
	// return ErrKeyNotFound.
	Touch(ctx context.Context, key K) error
	// Remove removes the specified key from the cache if the key is present.
	// Returns true if the key was present and the key has been deleted.
	Remove(key K) bool
	// Clear removes all key-value pairs from the cache.
	Clear()
	// Keys returns a slice containing all keys in the cache.
	Keys() []K
	// Len returns the number of items in the cache.
	Len() int
	// Has returns true if the key exists in the cache.
	Has(key K) bool
	// Compact clear expired items
	Compact() int
	// contains filtered or unexported methods
}

type CacheBuilder 

type CacheBuilder[K comparable, V any] struct {
	// contains filtered or unexported fields
}

func New 

func New[K comparable, V any](size int) *CacheBuilder[K, V]

func (*CacheBuilder[K, V]) ARC 

func (cb *CacheBuilder[K, V]) ARC() *CacheBuilder[K, V]

func (*CacheBuilder[K, V]) AddedFunc 

func (cb *CacheBuilder[K, V]) AddedFunc(addedFunc AddedFunc[K, V]) *CacheBuilder[K, V]

func (*CacheBuilder[K, V]) Arena 

func (cb *CacheBuilder[K, V]) Arena(opts ...arena.Option) *CacheBuilder[K, V]

func (*CacheBuilder[K, V]) AutoRenewal 

func (cb *CacheBuilder[K, V]) AutoRenewal(autoRenewal bool) *CacheBuilder[K, V]

func (*CacheBuilder[K, V]) Build 

func (cb *CacheBuilder[K, V]) Build() Cache[K, V]

func (*CacheBuilder[K, V]) Clock 

func (cb *CacheBuilder[K, V]) Clock(clock Clock) *CacheBuilder[K, V]

func (*CacheBuilder[K, V]) EvictType 

func (cb *CacheBuilder[K, V]) EvictType(tp string) *CacheBuilder[K, V]

func (*CacheBuilder[K, V]) EvictedFunc 

func (cb *CacheBuilder[K, V]) EvictedFunc(evictedFunc EvictedFunc[K, V]) *CacheBuilder[K, V]

func (*CacheBuilder[K, V]) Expiration 

func (cb *CacheBuilder[K, V]) Expiration(expiration time.Duration) *CacheBuilder[K, V]

func (*CacheBuilder[K, V]) LFU 

func (cb *CacheBuilder[K, V]) LFU() *CacheBuilder[K, V]

func (*CacheBuilder[K, V]) LRU 

func (cb *CacheBuilder[K, V]) LRU() *CacheBuilder[K, V]

func (*CacheBuilder[K, V]) LoaderExpireFunc 

func (cb *CacheBuilder[K, V]) LoaderExpireFunc(loaderExpireFunc LoaderExpireFunc[K, V]) *CacheBuilder[K, V]

LoaderExpireFunc Set a loader function with expiration. loaderExpireFunc: create a new value with this function if cached value is expired. If nil returned instead of time.Duration from loaderExpireFunc than value will never expire.

func (*CacheBuilder[K, V]) LoaderFunc 

func (cb *CacheBuilder[K, V]) LoaderFunc(loaderFunc LoaderFunc[K, V]) *CacheBuilder[K, V]

LoaderFunc Set a loader function. loaderFunc: create a new value with this function if cached value is expired.

func (*CacheBuilder[K, V]) NopLocker 

func (cb *CacheBuilder[K, V]) NopLocker() *CacheBuilder[K, V]

func (*CacheBuilder[K, V]) PurgeVisitorFunc 

func (cb *CacheBuilder[K, V]) PurgeVisitorFunc(purgeVisitorFunc PurgeVisitorFunc[K, V]) *CacheBuilder[K, V]

func (*CacheBuilder[K, V]) Shard 

func (cb *CacheBuilder[K, V]) Shard(shared int) *CacheBuilder[K, V]

func (*CacheBuilder[K, V]) Simple 

func (cb *CacheBuilder[K, V]) Simple() *CacheBuilder[K, V]

type Clock 

type Clock interface {
	Now() time.Time
}

func NewRealClock 

func NewRealClock() Clock

type EvictedFunc 

type EvictedFunc[K comparable, V any] func(K, *V)

type FakeClock 

type FakeClock interface {
	Clock

	Advance(d time.Duration)
}

func NewFakeClock 

func NewFakeClock() FakeClock

type LFUCache 

type LFUCache[K comparable, V any] struct {
	// contains filtered or unexported fields
}

Discards the least frequently used items first.

func (*LFUCache[K, V]) Clear 

func (c *LFUCache[K, V]) Clear()

Clear removes all key-value pairs from the cache

func (*LFUCache[K, V]) Compact 

func (c *LFUCache[K, V]) Compact() (n int)

Compact clear expired items

func (*LFUCache[K, V]) Get 

func (c *LFUCache[K, V]) Get(ctx context.Context, key K) (*V, error)

Get a value from cache pool using key if it exists. If it does not exists key and has LoaderFunc, generate a value using `LoaderFunc` method returns value.

func (*LFUCache[K, V]) GetFn 

func (c *LFUCache[K, V]) GetFn(ctx context.Context, key K, fn func(value *V, err error))

GetFn callbacks the value for the specified key if it is present in the cache. If the key is not present in the cache and the cache has LoaderFunc, invoke the `LoaderFunc` function and inserts the key-value pair in the cache. If the key is not present in the cache and the cache does not have a LoaderFunc, Callback ErrKeyNotFound.

func (*LFUCache[K, V]) GetIfPresent 

func (c *LFUCache[K, V]) GetIfPresent(ctx context.Context, key K) (*V, error)

GetIfPresent gets a value from cache pool using key if it exists. If it does not exists key, returns ErrKeyNotFound.

func (*LFUCache[K, V]) GetIfPresentFn 

func (c *LFUCache[K, V]) GetIfPresentFn(ctx context.Context, key K, fn func(value *V, err error))

GetIfPresentFn callbacks the value for the specified key if it is present in the cache. Callback ErrKeyNotFound if the key is not present.

func (*LFUCache[K, V]) Has 

func (c *LFUCache[K, V]) Has(key K) bool

Has checks if key exists in cache

func (*LFUCache[K, V]) Keys 

func (c *LFUCache[K, V]) Keys() []K

Keys returns a slice of the keys in the cache.

func (*LFUCache[K, V]) Len 

func (c *LFUCache[K, V]) Len() int

Len returns the number of items in the cache.

func (*LFUCache[K, V]) Remove 

func (c *LFUCache[K, V]) Remove(key K) bool

Remove removes the provided key from the cache.

func (*LFUCache[K, V]) Set 

func (c *LFUCache[K, V]) Set(key K, value *V) error

Set a new key-value pair

func (*LFUCache[K, V]) SetWithExpire 

func (c *LFUCache[K, V]) SetWithExpire(key K, value *V, expiration time.Duration) error

SetWithExpire a new key-value pair with an expiration time

func (*LFUCache[K, V]) Touch 

func (c *LFUCache[K, V]) Touch(ctx context.Context, key K) error

Touch updates the expiration time of an existing key. If the key is not present in the cache and the cache has LoaderFunc, invoke the `LoaderFunc` function and inserts the key-value pair in the cache. If the key is not present in the cache and the cache does not have a LoaderFunc, return ErrKeyNotFound.

type LRUCache 

type LRUCache[K comparable, V any] struct {
	// contains filtered or unexported fields
}

Discards the least recently used items first.

func (*LRUCache[K, V]) Clear 

func (c *LRUCache[K, V]) Clear()

Clear removes all key-value pairs from the cache

func (*LRUCache[K, V]) Compact 

func (c *LRUCache[K, V]) Compact() (n int)

Compact clear expired items

func (*LRUCache[K, V]) Get 

func (c *LRUCache[K, V]) Get(ctx context.Context, key K) (*V, error)

Get a value from cache pool using key if it exists. If it does not exists key and has LoaderFunc, generate a value using `LoaderFunc` method returns value.

func (*LRUCache[K, V]) GetFn 

func (c *LRUCache[K, V]) GetFn(ctx context.Context, key K, fn func(value *V, err error))

GetFn callbacks the value for the specified key if it is present in the cache. If the key is not present in the cache and the cache has LoaderFunc, invoke the `LoaderFunc` function and inserts the key-value pair in the cache. If the key is not present in the cache and the cache does not have a LoaderFunc, Callback ErrKeyNotFound.

func (*LRUCache[K, V]) GetIfPresent 

func (c *LRUCache[K, V]) GetIfPresent(ctx context.Context, key K) (*V, error)

GetIfPresent gets a value from cache pool using key if it exists. If it does not exists key, returns ErrKeyNotFound.

func (*LRUCache[K, V]) GetIfPresentFn 

func (c *LRUCache[K, V]) GetIfPresentFn(ctx context.Context, key K, fn func(value *V, err error))

GetIfPresentFn callbacks the value for the specified key if it is present in the cache. Callback ErrKeyNotFound if the key is not present.

func (*LRUCache[K, V]) Has 

func (c *LRUCache[K, V]) Has(key K) bool

Has checks if key exists in cache

func (*LRUCache[K, V]) Keys 

func (c *LRUCache[K, V]) Keys() []K

Keys returns a slice of the keys in the cache.

func (*LRUCache[K, V]) Len 

func (c *LRUCache[K, V]) Len() int

Len returns the number of items in the cache.

func (*LRUCache[K, V]) Remove 

func (c *LRUCache[K, V]) Remove(key K) bool

Remove removes the provided key from the cache.

func (*LRUCache[K, V]) Set 

func (c *LRUCache[K, V]) Set(key K, value *V) error

Set a new key-value pair

func (*LRUCache[K, V]) SetWithExpire 

func (c *LRUCache[K, V]) SetWithExpire(key K, value *V, expiration time.Duration) error

SetWithExpire a new key-value pair with an expiration time

func (*LRUCache[K, V]) Touch 

func (c *LRUCache[K, V]) Touch(ctx context.Context, key K) error

Touch updates the expiration time of an existing key. If the key is not present in the cache and the cache has LoaderFunc, invoke the `LoaderFunc` function and inserts the key-value pair in the cache. If the key is not present in the cache and the cache does not have a LoaderFunc, return ErrKeyNotFound.

type LoaderExpireFunc 

type LoaderExpireFunc[K comparable, V any] func(context.Context, K) (*V, time.Duration, error)

type LoaderFunc 

type LoaderFunc[K comparable, V any] func(context.Context, K) (*V, error)

type PurgeVisitorFunc 

type PurgeVisitorFunc[K comparable, V any] func(K, *V)

type RWMutex 

type RWMutex interface {
	sync.Locker
	RLock()
	RUnlock()
}

type RealClock 

type RealClock struct{}

func (RealClock) Now 

func (rc RealClock) Now() time.Time

type SimpleCache 

type SimpleCache[K comparable, V any] struct {
	// contains filtered or unexported fields
}

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

func (*SimpleCache[K, V]) Clear 

func (c *SimpleCache[K, V]) Clear()

Clear removes all key-value pairs from the cache

func (*SimpleCache[K, V]) Compact 

func (c *SimpleCache[K, V]) Compact() (n int)

Compact clear expired items

func (*SimpleCache[K, V]) Get 

func (c *SimpleCache[K, V]) Get(ctx context.Context, key K) (*V, error)

Get a value from cache pool using key if it exists. If it does not exists key and has LoaderFunc, generate a value using `LoaderFunc` method returns value.

func (*SimpleCache[K, V]) GetFn 

func (c *SimpleCache[K, V]) GetFn(ctx context.Context, key K, fn func(value *V, err error))

GetFn callbacks the value for the specified key if it is present in the cache. If the key is not present in the cache and the cache has LoaderFunc, invoke the `LoaderFunc` function and inserts the key-value pair in the cache. If the key is not present in the cache and the cache does not have a LoaderFunc, Callback ErrKeyNotFound.

func (*SimpleCache[K, V]) GetIfPresent 

func (c *SimpleCache[K, V]) GetIfPresent(ctx context.Context, key K) (*V, error)

GetIfPresent gets a value from cache pool using key if it exists. If it does not exists key, returns ErrKeyNotFound.

func (*SimpleCache[K, V]) GetIfPresentFn 

func (c *SimpleCache[K, V]) GetIfPresentFn(ctx context.Context, key K, fn func(value *V, err error))

GetIfPresentFn callbacks the value for the specified key if it is present in the cache. Callback ErrKeyNotFound if the key is not present.

func (*SimpleCache[K, V]) Has 

func (c *SimpleCache[K, V]) Has(key K) bool

Has checks if key exists in cache

func (*SimpleCache[K, V]) Keys 

func (c *SimpleCache[K, V]) Keys() []K

Keys returns a slice of the keys in the cache.

func (*SimpleCache[K, V]) Len 

func (c *SimpleCache[K, V]) Len() int

Len returns the number of items in the cache.

func (*SimpleCache[K, V]) Remove 

func (c *SimpleCache[K, V]) Remove(key K) bool

Remove removes the provided key from the cache.

func (*SimpleCache[K, V]) Set 

func (c *SimpleCache[K, V]) Set(key K, value *V) error

Set a new key-value pair

func (*SimpleCache[K, V]) SetWithExpire 

func (c *SimpleCache[K, V]) SetWithExpire(key K, value *V, expiration time.Duration) error

SetWithExpire set a new key-value pair with an expiration time

func (*SimpleCache[K, V]) Touch 

func (c *SimpleCache[K, V]) Touch(ctx context.Context, key K) error

Touch updates the expiration time of an existing key. If the key is not present in the cache and the cache has LoaderFunc, invoke the `LoaderFunc` function and inserts the key-value pair in the cache. If the key is not present in the cache and the cache does not have a LoaderFunc, return ErrKeyNotFound.

Source Files

View all Source files

Directories

Path Synopsis
internal
pqueue

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.