sfcache

Documentation

Overview

Package sfcache provides a simple, local, thread-safe, fixed-size, and single-flight cache for expensive lookup calls.

This package is designed to improve the performance of expensive, slow, or high-frequency function calls that retrieve data associated with a unique identifier (key). It achieves this by caching previous values, eliminating the need for repeated expensive requests.

The sfcache package offers a local in-memory cache with a configurable maximum number of entries. The fixed-size nature of the cache ensures efficient memory management and prevents excessive memory usage. Additionally, the cache is thread-safe, allowing concurrent access without the need for external synchronization. It efficiently handles concurrent requests by sharing results from the first lookup, ensuring that only one request performs the expensive call. This approach avoids unnecessary network load or resource starvation. Duplicate calls for the same key will wait for the first call to complete and return the same value.

Each cache entry has a time-to-live (TTL) value, which determines its expiration. The cache also provides methods to force the removal of a specific entry or reset the entire cache.

The sfcache package is ideal for any Go application that heavily relies on expensive or slow lookups.

Example applications that can benefit from this package include:

• github.com/Vonage/gosrvlib/pkg/awssecretcache
• github.com/Vonage/gosrvlib/pkg/dnscache

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.