cache

Documentation

Overview

Package cache implements a generic, in-memory, TTL-based cache for any object.

Every entry shares the same expiration duration, configured when the cache is created. A background goroutine periodically purges expired entries; call Cache.Stop to release it when the cache is no longer needed.

The zero value is not usable; construct a cache with New.

Index

• Variables
• type Cache
  • func New[T any](expireAfter time.Duration) (*Cache[T], error)
  • func (c *Cache[T]) Clear()
  • func (c *Cache[T]) Lookup(name string) (T, bool)
  • func (c *Cache[T]) Set(name string, object T) error
  • func (c *Cache[T]) Size() int
  • func (c *Cache[T]) Stop()
  • func (c *Cache[T]) WriteThruLookup(name string, primaryLookup Func[T]) (T, error)
• type Func

Examples

• Cache
• Cache.WriteThruLookup

Variables

var ErrInvalidDuration = errors.New("expireAfter duration cannot be negative")

ErrInvalidDuration is returned by New when the provided expiration is negative.

Types

type Cache

type Cache[T any] struct {
	// contains filtered or unexported fields
}

Cache is a generic, thread-safe, in-memory cache where every entry expires after the same duration. It is safe for concurrent use by multiple goroutines.

Example

package main

import (
	"fmt"
	"time"

	"github.com/mikehelmick/go-bananas/cache"
)

func main() {
	// Create a cache of strings whose entries expire after one minute.
	c, err := cache.New[string](time.Minute)
	if err != nil {
		panic(err)
	}
	defer c.Stop()

	if err := c.Set("greeting", "hello"); err != nil {
		panic(err)
	}

	if v, ok := c.Lookup("greeting"); ok {
		fmt.Println(v)
	}
}

Output:
hello

func New

func New[T any](expireAfter time.Duration) (*Cache[T], error)

New creates a new in-memory cache whose entries expire after the given duration. It returns ErrInvalidDuration if expireAfter is negative. The caller is responsible for calling Cache.Stop to stop the background expiration goroutine.

func (*Cache[T]) Clear

func (c *Cache[T]) Clear()

Clear removes all items from the cache, regardless of their expiration.

func (*Cache[T]) Lookup

func (c *Cache[T]) Lookup(name string) (T, bool)

Lookup checks the cache for a non-expired object stored under name. The boolean return informs the caller whether there was a cache hit. A return of (zero, true) means the zero value is cached; (zero, false) indicates a miss or an expired value that should be refreshed.

func (*Cache[T]) Set

func (c *Cache[T]) Set(name string, object T) error

Set saves the current value of an object in the cache. The entry expires after the duration configured when the cache was created.

func (*Cache[T]) Size

func (c *Cache[T]) Size() int

Size returns the number of items in the cache.

func (*Cache[T]) Stop

func (c *Cache[T]) Stop()

Stop shuts down the background cleanup goroutine for the cache. It is safe to call multiple times. After Stop is called the cache should no longer be used.

func (*Cache[T]) WriteThruLookup

func (c *Cache[T]) WriteThruLookup(name string, primaryLookup Func[T]) (T, error)

WriteThruLookup checks the cache for the value associated with name, and if not found or expired, invokes the provided primaryLookup function to compute the value, storing and returning it. Concurrent callers for the same missing key are coalesced so that primaryLookup runs at most once.

Example

package main

import (
	"fmt"
	"time"

	"github.com/mikehelmick/go-bananas/cache"
)

func main() {
	c, err := cache.New[int](time.Minute)
	if err != nil {
		panic(err)
	}
	defer c.Stop()

	calls := 0
	expensive := func() (int, error) {
		calls++
		return 42, nil
	}

	// The first call computes the value; the second is served from the cache.
	if _, err := c.WriteThruLookup("answer", expensive); err != nil {
		panic(err)
	}
	v, _ := c.WriteThruLookup("answer", expensive)

	fmt.Println(v, calls)
}

Output:
42 1

type Func

type Func[T any] func() (T, error)

Func is the signature of the lookup function passed to Cache.WriteThruLookup. It computes the value for a missing key.