sfcache

Documentation

Overview

Package sfcache provides a thread-safe local single-flight cache for external lookup calls. The cache has a maximum size and a time-to-live (TTL) for each entry. Duplicate external calls for the same key will wait for the first call to complete and return the same value.

Index

• type Cache
  • func New(lookupFn LookupFunc, size int, ttl time.Duration) *Cache
  • func (c *Cache) Len() int
  • func (c *Cache) Lookup(ctx context.Context, key string) (any, error)
  • func (c *Cache) Remove(key string)
  • func (c *Cache) Reset()
• type LookupFunc

Examples

• Cache.Lookup

Types

type Cache

type Cache struct {
	// contains filtered or unexported fields
}

Cache represents a cache for items.

func New

func New(lookupFn LookupFunc, size int, ttl time.Duration) *Cache

New creates a new single-flight cache of the specified size and TTL. The lookup function performs the external call for each cache miss. The size parameter determines the maximum number of entries that can be cached (min = 1). If the size is less than or equal to zero, the cache will have a default size of 1. The ttl parameter specifies the time-to-live for each cached entry.

func (*Cache) Len

func (c *Cache) Len() int

Len returns the number of items in the cache.

func (*Cache) Lookup

func (c *Cache) Lookup(ctx context.Context, key string) (any, error)

Lookup performs a lookup for the given key. Duplicate lookup calls for the same key will wait for the first lookup to complete (single-flight). This function uses a mutex lock to ensure thread safety. It also handles the case where the cache entry is removed or updated during the wait. The function returns the cached value if available; otherwise, it performs a new lookup. If the external lookup call is successful, it updates the cache with the newly obtained value.

Example

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/Vonage/gosrvlib/pkg/sfcache"
)

func main() {
	// example lookup function that returns the key as value.
	lookupFn := func(_ context.Context, key string) (any, error) {
		return key, nil
	}

	// create a new cache with a lookupFn function, a maximum number of 3 entries, and a TTL of 1 minute.
	c := sfcache.New(lookupFn, 3, 1*time.Minute)

	val, err := c.Lookup(context.TODO(), "some_key")

	fmt.Println(val, err)

}

Output:

some_key <nil>

func (*Cache) Remove

func (c *Cache) Remove(key string)

Remove removes the cache entry for the specified key.

func (*Cache) Reset

func (c *Cache) Reset()

Reset clears the whole cache.

type LookupFunc

type LookupFunc func(ctx context.Context, key string) (any, error)

LookupFunc is the generic function signature for external lookup calls.