evcache

README

evcache

Package evcache implements a concurrent key-value cache with capacity overflow eviction, item expiry and deduplication.

import "github.com/mgnsk/evcache/v3"

Package evcache implements a concurrent key-value cache with capacity overflow eviction, item expiry and deduplication.

Example

c := evcache.New[string, string](10)

// Fetches an existing value or calls the callback to get a new value.
result, err := c.Fetch("key", time.Minute, func() (string, error) {
	// Possibly a very long network call. It only blocks write access to this key.
	// Read access to the key is always non-blocking.
	return "value", nil
})

if err != nil {
    return err
}

// Use the result.
_ = result

Documentation

Overview

Package evcache implements a concurrent key-value cache with capacity overflow eviction, item expiry and deduplication.

Package evcache implements a key-value cache with capacity overflow eviction, item expiry and deduplication.

Index

• type Cache
  • func New[K comparable, V any](capacity int) *Cache[K, V]
  • func (c *Cache[K, V]) Evict(key K) (value V, ok bool)
  • func (c *Cache[K, V]) Exists(key K) bool
  • func (c *Cache[K, V]) Fetch(key K, ttl time.Duration, f func() (V, error)) (value V, err error)
  • func (c *Cache[K, V]) Get(key K) (value V, exists bool)
  • func (c *Cache[K, V]) Len() int
  • func (c *Cache[K, V]) LoadOrStore(key K, ttl time.Duration, value V) (old V, loaded bool)
  • func (c *Cache[K, V]) MustFetch(key K, ttl time.Duration, f func() V) (value V)
  • func (c *Cache[K, V]) Range(f func(key K, value V) bool)
  • func (c *Cache[K, V]) TryFetch(key K, f func() (V, time.Duration, error)) (value V, err error)

Types

type Cache

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

Cache is an in-memory TTL cache with optional capacity.

func New

func New[K comparable, V any](capacity int) *Cache[K, V]

New creates an empty cache.

func (*Cache[K, V]) Evict

func (c *Cache[K, V]) Evict(key K) (value V, ok bool)

Evict a key and return its value.

func (*Cache[K, V]) Exists

func (c *Cache[K, V]) Exists(key K) bool

Exists returns whether a value in the cache exists for key.

func (*Cache[K, V]) Fetch

func (c *Cache[K, V]) Fetch(key K, ttl time.Duration, f func() (V, error)) (value V, err error)

Fetch loads or stores a value for key. If a value exists, f will not be called, otherwise f will be called to fetch the new value. It panics if f panics. Concurrent Fetches for the same key will block each other and return a single result.

func (*Cache[K, V]) Get

func (c *Cache[K, V]) Get(key K) (value V, exists bool)

Get returns the value stored in the cache for key.

func (*Cache[K, V]) Len

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

Len returns the number of keys in the cache.

func (*Cache[K, V]) LoadOrStore

func (c *Cache[K, V]) LoadOrStore(key K, ttl time.Duration, value V) (old V, loaded bool)

LoadOrStore loads or stores a value for key. If the key is being Fetched, LoadOrStore blocks until Fetch returns.

func (*Cache[K, V]) MustFetch

func (c *Cache[K, V]) MustFetch(key K, ttl time.Duration, f func() V) (value V)

MustFetch fetches a value or panics if f panics.

func (*Cache[K, V]) Range

func (c *Cache[K, V]) Range(f func(key K, value V) bool)

Range calls f for each key and value present in the cache in no particular order or consistency. If f returns false, Range stops the iteration. It skips values that are currently being Fetched.

Range is allowed to modify the cache.

func (*Cache[K, V]) TryFetch

func (c *Cache[K, V]) TryFetch(key K, f func() (V, time.Duration, error)) (value V, err error)

TryFetch is like Fetch but allows the TTL to be returned alongside the value from callback.