cache: generic cache implementation

Signed-off-by: Hank Donnay <[email protected]>

Author: hdonnay

internal/cache/cache.go

@@ -0,0 +1,86 @@
+//go:build go1.24
+
+package cache
+
+import (
+	"context"
+	"runtime"
+	"sync"
+	"unique"
+	"weak"
+
+	"github.com/quay/claircore/internal/singleflight"
+)
+
+// Live is a cache that keeps a cached copy as long as the go runtime determines
+// the value is live.
+//
+// See also: [weak.Pointer].
+type Live[K comparable, V any] struct {
+	create func(context.Context, K) (*V, error)
+	m      sync.Map
+	sf     singleflight.Group[K, *V]
+}
+
+// NewLive ...
+//
+// If the "create" function needs a struct to be able to construct a value,
+// consider using [unique.Handle] to be able to satisfy the "comparable"
+// constraint.
+func NewLive[K comparable, V any](create func(context.Context, K) (*V, error)) *Live[K, V] {
+	return &Live[K, V]{create: create}
+}
+
+var _ unique.Handle[string] // for docs
+
+// Get ...
+func (c *Live[K, V]) Get(ctx context.Context, key K) (*V, error) {
+	for {
+		// Try to load an existing value out of the cache.
+		value, ok := c.m.Load(key)
+		if !ok {
+			// No value found. Create a new value.
+			fn := func() (*V, error) {
+				// Eagerly check the Context so that every create function
+				// doesn't need the preamble.
+				//
+				// Do this because this goroutine may have gone around the loop
+				// multiple times and found entries in the map that had
+				// invalidated weak pointers, so the context may have exprired.
+				if ctx.Err() != nil {
+					return nil, context.Cause(ctx)
+				}
+				v, err := c.create(ctx, key)
+				if err != nil {
+					return nil, err
+				}
+
+				wp := weak.Make(v)
+				c.m.Store(key, wp)
+				runtime.AddCleanup(v, func(key K) {
+					// Only delete if the weak pointer is equal. If it's not,
+					// someone else already deleted the entry and installed a
+					// new pointer.
+					c.m.CompareAndDelete(key, wp)
+				}, key)
+				return v, nil
+			}
+
+			ch := c.sf.DoChan(key, fn)
+			select {
+			case res := <-ch:
+				return res.Val, res.Err
+			case <-ctx.Done():
+				c.sf.Forget(key)
+				return nil, context.Cause(ctx)
+			}
+		}
+
+		// See if our cache entry is valid.
+		if v := value.(weak.Pointer[V]).Value(); v != nil {
+			return v, nil
+		}
+		// Discovered a nil entry awaiting cleanup. Eagerly delete it.
+		c.m.CompareAndDelete(key, value)
+	}
+}

internal/cache/doc.go

@@ -0,0 +1,2 @@
+// Package cache provides caching implementations for Go values.
+package cache