OP#792 initial commit after fork

internal/cachevalue/cache.go

@@ -0,0 +1,156 @@
+// Copyright (c) 2015-2024 MinIO, Inc.
+//
+// This file is part of MinIO Object Storage stack
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+package cachevalue
+
+import (
+	"context"
+	"sync"
+	"sync/atomic"
+	"time"
+)
+
+// Opts contains options for the cache.
+type Opts struct {
+	// When set to true, return the last cached value
+	// even if updating the value errors out.
+	// Returns the last good value AND the error.
+	ReturnLastGood bool
+
+	// If NoWait is set, Get() will return the last good value,
+	// if TTL has expired but 2x TTL has not yet passed,
+	// but will fetch a new value in the background.
+	NoWait bool
+}
+
+// Cache contains a synchronized value that is considered valid
+// for a specific amount of time.
+// An Update function must be set to provide an updated value when needed.
+type Cache[T any] struct {
+	// updateFn must return an updated value.
+	// If an error is returned the cached value is not set.
+	// Only one caller will call this function at any time, others will be blocking.
+	// The returned value can no longer be modified once returned.
+	// Should be set before calling Get().
+	updateFn func(ctx context.Context) (T, error)
+
+	// ttl for a cached value.
+	ttl time.Duration
+
+	opts Opts
+
+	// Once can be used to initialize values for lazy initialization.
+	// Should be set before calling Get().
+	Once sync.Once
+
+	// Managed values.
+	val          atomic.Pointer[T]
+	lastUpdateMs atomic.Int64
+	updating     sync.Mutex
+}
+
+// New allocates a new cached value instance. Tt must be initialized with
+// `.TnitOnce`.
+func New[T any]() *Cache[T] {
+	return &Cache[T]{}
+}
+
+// NewFromFunc allocates a new cached value instance and initializes it with an
+// update function, making it ready for use.
+func NewFromFunc[T any](ttl time.Duration, opts Opts, update func(ctx context.Context) (T, error)) *Cache[T] {
+	return &Cache[T]{
+		ttl:      ttl,
+		updateFn: update,
+		opts:     opts,
+	}
+}
+
+// InitOnce initializes the cache with a TTL and an update function. It is
+// guaranteed to be called only once.
+func (t *Cache[T]) InitOnce(ttl time.Duration, opts Opts, update func(ctx context.Context) (T, error)) {
+	t.Once.Do(func() {
+		t.ttl = ttl
+		t.updateFn = update
+		t.opts = opts
+	})
+}
+
+// GetWithCtx will return a cached value or fetch a new one.
+// passes a caller context, if caller context cancels nothing
+// is cached.
+// If the Update function returns an error the value is forwarded as is and not cached.
+func (t *Cache[T]) GetWithCtx(ctx context.Context) (T, error) {
+	v := t.val.Load()
+	ttl := t.ttl
+	vTime := t.lastUpdateMs.Load()
+	tNow := time.Now().UnixMilli()
+	if v != nil && tNow-vTime < ttl.Milliseconds() {
+		return *v, nil
+	}
+
+	// Fetch new value asynchronously, while we do not return an error
+	// if v != nil value or
+	if t.opts.NoWait && v != nil && tNow-vTime < ttl.Milliseconds()*2 {
+		if t.updating.TryLock() {
+			go func() {
+				defer t.updating.Unlock()
+				t.update(context.Background())
+			}()
+		}
+		return *v, nil
+	}
+
+	// Get lock. Either we get it or we wait for it.
+	t.updating.Lock()
+	defer t.updating.Unlock()
+
+	if time.Since(time.UnixMilli(t.lastUpdateMs.Load())) < ttl {
+		// There is a new value, release lock and return it.
+		if v = t.val.Load(); v != nil {
+			return *v, nil
+		}
+	}
+
+	if err := t.update(ctx); err != nil {
+		var empty T
+		return empty, err
+	}
+
+	return *t.val.Load(), nil
+}
+
+// Get will return a cached value or fetch a new one.
+// Tf the Update function returns an error the value is forwarded as is and not cached.
+func (t *Cache[T]) Get() (T, error) {
+	return t.GetWithCtx(context.Background())
+}
+
+func (t *Cache[T]) update(ctx context.Context) error {
+	val, err := t.updateFn(ctx)
+	if err != nil {
+		if t.opts.ReturnLastGood && t.val.Load() != nil {
+			// Keep last good value, so update
+			// does not return an error.
+			return nil
+		}
+		return err
+	}
+
+	t.val.Store(&val)
+	t.lastUpdateMs.Store(time.Now().UnixMilli())
+	return nil
+}