422 lines
10 KiB
Go
422 lines
10 KiB
Go
package result
|
|
|
|
import (
|
|
"context"
|
|
"reflect"
|
|
"time"
|
|
_ "unsafe"
|
|
|
|
"codeberg.org/gruf/go-cache/v3/ttl"
|
|
"codeberg.org/gruf/go-errors/v2"
|
|
)
|
|
|
|
// Lookup represents a struct object lookup method in the cache.
|
|
type Lookup struct {
|
|
// Name is a period ('.') separated string
|
|
// of struct fields this Key encompasses.
|
|
Name string
|
|
|
|
// AllowZero indicates whether to accept and cache
|
|
// under zero value keys, otherwise ignore them.
|
|
AllowZero bool
|
|
|
|
// Multi allows specifying a key capable of storing
|
|
// multiple results. Note this only supports invalidate.
|
|
Multi bool
|
|
|
|
// TODO: support toggling case sensitive lookups.
|
|
// CaseSensitive bool
|
|
}
|
|
|
|
// Cache provides a means of caching value structures, along with
|
|
// the results of attempting to load them. An example usecase of this
|
|
// cache would be in wrapping a database, allowing caching of sql.ErrNoRows.
|
|
type Cache[Value any] struct {
|
|
cache ttl.Cache[int64, result[Value]] // underlying result cache
|
|
invalid func(Value) // store unwrapped invalidate callback.
|
|
lookups structKeys // pre-determined struct lookups
|
|
ignore func(error) bool // determines cacheable errors
|
|
copy func(Value) Value // copies a Value type
|
|
next int64 // update key counter
|
|
}
|
|
|
|
// New returns a new initialized Cache, with given lookups, underlying value copy function and provided capacity.
|
|
func New[Value any](lookups []Lookup, copy func(Value) Value, cap int) *Cache[Value] {
|
|
var z Value
|
|
|
|
// Determine generic type
|
|
t := reflect.TypeOf(z)
|
|
|
|
// Iteratively deref pointer type
|
|
for t.Kind() == reflect.Pointer {
|
|
t = t.Elem()
|
|
}
|
|
|
|
// Ensure that this is a struct type
|
|
if t.Kind() != reflect.Struct {
|
|
panic("generic parameter type must be struct (or ptr to)")
|
|
}
|
|
|
|
// Allocate new cache object
|
|
c := &Cache[Value]{copy: copy}
|
|
c.lookups = make([]structKey, len(lookups))
|
|
|
|
for i, lookup := range lookups {
|
|
// Create keyed field info for lookup
|
|
c.lookups[i] = newStructKey(lookup, t)
|
|
}
|
|
|
|
// Create and initialize underlying cache
|
|
c.cache.Init(0, cap, 0)
|
|
c.SetEvictionCallback(nil)
|
|
c.SetInvalidateCallback(nil)
|
|
c.IgnoreErrors(nil)
|
|
return c
|
|
}
|
|
|
|
// Start will start the cache background eviction routine with given sweep frequency. If already
|
|
// running or a freq <= 0 provided, this is a no-op. This will block until eviction routine started.
|
|
func (c *Cache[Value]) Start(freq time.Duration) bool {
|
|
return c.cache.Start(freq)
|
|
}
|
|
|
|
// Stop will stop cache background eviction routine. If not running this
|
|
// is a no-op. This will block until the eviction routine has stopped.
|
|
func (c *Cache[Value]) Stop() bool {
|
|
return c.cache.Stop()
|
|
}
|
|
|
|
// SetTTL sets the cache item TTL. Update can be specified to force updates of existing items
|
|
// in the cache, this will simply add the change in TTL to their current expiry time.
|
|
func (c *Cache[Value]) SetTTL(ttl time.Duration, update bool) {
|
|
c.cache.SetTTL(ttl, update)
|
|
}
|
|
|
|
// SetEvictionCallback sets the eviction callback to the provided hook.
|
|
func (c *Cache[Value]) SetEvictionCallback(hook func(Value)) {
|
|
if hook == nil {
|
|
// Ensure non-nil hook.
|
|
hook = func(Value) {}
|
|
}
|
|
c.cache.SetEvictionCallback(func(pkey int64, res result[Value]) {
|
|
c.cache.Lock()
|
|
for _, key := range res.Keys {
|
|
// Delete key->pkey lookup
|
|
pkeys := key.info.pkeys
|
|
delete(pkeys, key.key)
|
|
}
|
|
c.cache.Unlock()
|
|
|
|
if res.Error != nil {
|
|
// Skip error hooks
|
|
return
|
|
}
|
|
|
|
// Call user hook.
|
|
hook(res.Value)
|
|
})
|
|
}
|
|
|
|
// SetInvalidateCallback sets the invalidate callback to the provided hook.
|
|
func (c *Cache[Value]) SetInvalidateCallback(hook func(Value)) {
|
|
if hook == nil {
|
|
// Ensure non-nil hook.
|
|
hook = func(Value) {}
|
|
} // store hook.
|
|
c.invalid = hook
|
|
c.cache.SetInvalidateCallback(func(pkey int64, res result[Value]) {
|
|
c.cache.Lock()
|
|
for _, key := range res.Keys {
|
|
// Delete key->pkey lookup
|
|
pkeys := key.info.pkeys
|
|
delete(pkeys, key.key)
|
|
}
|
|
c.cache.Unlock()
|
|
|
|
if res.Error != nil {
|
|
// Skip error hooks
|
|
return
|
|
}
|
|
|
|
// Call user hook.
|
|
hook(res.Value)
|
|
})
|
|
}
|
|
|
|
// IgnoreErrors allows setting a function hook to determine which error types should / not be cached.
|
|
func (c *Cache[Value]) IgnoreErrors(ignore func(error) bool) {
|
|
if ignore == nil {
|
|
ignore = func(err error) bool {
|
|
return errors.Comparable(
|
|
err,
|
|
context.Canceled,
|
|
context.DeadlineExceeded,
|
|
)
|
|
}
|
|
}
|
|
c.cache.Lock()
|
|
c.ignore = ignore
|
|
c.cache.Unlock()
|
|
}
|
|
|
|
// Load will attempt to load an existing result from the cacche for the given lookup and key parts, else calling the provided load function and caching the result.
|
|
func (c *Cache[Value]) Load(lookup string, load func() (Value, error), keyParts ...any) (Value, error) {
|
|
var (
|
|
zero Value
|
|
res result[Value]
|
|
ok bool
|
|
)
|
|
|
|
// Get lookup key info by name.
|
|
keyInfo := c.lookups.get(lookup)
|
|
if !keyInfo.unique {
|
|
panic("non-unique lookup does not support load: " + lookup)
|
|
}
|
|
|
|
// Generate cache key string.
|
|
ckey := keyInfo.genKey(keyParts)
|
|
|
|
// Acquire cache lock
|
|
c.cache.Lock()
|
|
|
|
// Look for primary cache key
|
|
pkeys := keyInfo.pkeys[ckey]
|
|
|
|
if ok = (len(pkeys) > 0); ok {
|
|
var entry *ttl.Entry[int64, result[Value]]
|
|
|
|
// Fetch the result for primary key
|
|
entry, ok = c.cache.Cache.Get(pkeys[0])
|
|
if ok {
|
|
// Since the invalidation / eviction hooks acquire a mutex
|
|
// lock separately, and only at this point are the pkeys
|
|
// updated, there is a chance that a primary key may return
|
|
// no matching entry. Hence we have to check for it here.
|
|
res = entry.Value
|
|
}
|
|
}
|
|
|
|
// Done with lock
|
|
c.cache.Unlock()
|
|
|
|
if !ok {
|
|
// Generate fresh result.
|
|
value, err := load()
|
|
|
|
if err != nil {
|
|
if c.ignore(err) {
|
|
// don't cache this error type
|
|
return zero, err
|
|
}
|
|
|
|
// Store error result.
|
|
res.Error = err
|
|
|
|
// This load returned an error, only
|
|
// store this item under provided key.
|
|
res.Keys = []cacheKey{{
|
|
info: keyInfo,
|
|
key: ckey,
|
|
}}
|
|
} else {
|
|
// Store value result.
|
|
res.Value = value
|
|
|
|
// This was a successful load, generate keys.
|
|
res.Keys = c.lookups.generate(res.Value)
|
|
}
|
|
|
|
var evict func()
|
|
|
|
// Acquire cache lock.
|
|
c.cache.Lock()
|
|
defer func() {
|
|
c.cache.Unlock()
|
|
if evict != nil {
|
|
evict()
|
|
}
|
|
}()
|
|
|
|
// Store result in cache.
|
|
evict = c.store(res)
|
|
}
|
|
|
|
// Catch and return error
|
|
if res.Error != nil {
|
|
return zero, res.Error
|
|
}
|
|
|
|
// Return a copy of value from cache
|
|
return c.copy(res.Value), nil
|
|
}
|
|
|
|
// Store will call the given store function, and on success store the value in the cache as a positive result.
|
|
func (c *Cache[Value]) Store(value Value, store func() error) error {
|
|
// Attempt to store this value.
|
|
if err := store(); err != nil {
|
|
return err
|
|
}
|
|
|
|
// Prepare cached result.
|
|
result := result[Value]{
|
|
Keys: c.lookups.generate(value),
|
|
Value: c.copy(value),
|
|
Error: nil,
|
|
}
|
|
|
|
var evict func()
|
|
|
|
// Acquire cache lock.
|
|
c.cache.Lock()
|
|
defer func() {
|
|
c.cache.Unlock()
|
|
if evict != nil {
|
|
evict()
|
|
}
|
|
}()
|
|
|
|
// Store result in cache.
|
|
evict = c.store(result)
|
|
|
|
// Call invalidate.
|
|
c.invalid(value)
|
|
|
|
return nil
|
|
}
|
|
|
|
// Has checks the cache for a positive result under the given lookup and key parts.
|
|
func (c *Cache[Value]) Has(lookup string, keyParts ...any) bool {
|
|
var res result[Value]
|
|
var ok bool
|
|
|
|
// Get lookup key info by name.
|
|
keyInfo := c.lookups.get(lookup)
|
|
if !keyInfo.unique {
|
|
panic("non-unique lookup does not support has: " + lookup)
|
|
}
|
|
|
|
// Generate cache key string.
|
|
ckey := keyInfo.genKey(keyParts)
|
|
|
|
// Acquire cache lock
|
|
c.cache.Lock()
|
|
|
|
// Look for primary key for cache key
|
|
pkeys := keyInfo.pkeys[ckey]
|
|
|
|
if ok = (len(pkeys) > 0); ok {
|
|
var entry *ttl.Entry[int64, result[Value]]
|
|
|
|
// Fetch the result for primary key
|
|
entry, ok = c.cache.Cache.Get(pkeys[0])
|
|
if ok {
|
|
// Since the invalidation / eviction hooks acquire a mutex
|
|
// lock separately, and only at this point are the pkeys
|
|
// updated, there is a chance that a primary key may return
|
|
// no matching entry. Hence we have to check for it here.
|
|
res = entry.Value
|
|
}
|
|
}
|
|
|
|
// Done with lock
|
|
c.cache.Unlock()
|
|
|
|
// Check for non-error result.
|
|
return ok && (res.Error == nil)
|
|
}
|
|
|
|
// Invalidate will invalidate any result from the cache found under given lookup and key parts.
|
|
func (c *Cache[Value]) Invalidate(lookup string, keyParts ...any) {
|
|
// Get lookup key info by name.
|
|
keyInfo := c.lookups.get(lookup)
|
|
|
|
// Generate cache key string.
|
|
ckey := keyInfo.genKey(keyParts)
|
|
|
|
// Look for primary key for cache key
|
|
c.cache.Lock()
|
|
pkeys := keyInfo.pkeys[ckey]
|
|
delete(keyInfo.pkeys, ckey)
|
|
c.cache.Unlock()
|
|
|
|
// Invalidate all primary keys.
|
|
c.cache.InvalidateAll(pkeys...)
|
|
}
|
|
|
|
// Clear empties the cache, calling the invalidate callback.
|
|
func (c *Cache[Value]) Clear() { c.cache.Clear() }
|
|
|
|
// store will cache this result under all of its required cache keys.
|
|
func (c *Cache[Value]) store(res result[Value]) (evict func()) {
|
|
// Get primary key
|
|
pnext := c.next
|
|
c.next++
|
|
if pnext > c.next {
|
|
panic("cache primary key overflow")
|
|
}
|
|
|
|
for _, key := range res.Keys {
|
|
// Look for cache primary keys.
|
|
pkeys := key.info.pkeys[key.key]
|
|
|
|
if key.info.unique && len(pkeys) > 0 {
|
|
for _, conflict := range pkeys {
|
|
// Get the overlapping result with this key.
|
|
entry, _ := c.cache.Cache.Get(conflict)
|
|
|
|
// From conflicting entry, drop this key, this
|
|
// will prevent eviction cleanup key confusion.
|
|
entry.Value.Keys.drop(key.info.name)
|
|
|
|
if len(entry.Value.Keys) == 0 {
|
|
// We just over-wrote the only lookup key for
|
|
// this value, so we drop its primary key too.
|
|
c.cache.Cache.Delete(conflict)
|
|
}
|
|
}
|
|
|
|
// Drop existing.
|
|
pkeys = pkeys[:0]
|
|
}
|
|
|
|
// Store primary key lookup.
|
|
pkeys = append(pkeys, pnext)
|
|
key.info.pkeys[key.key] = pkeys
|
|
}
|
|
|
|
// Store main entry under primary key, using evict hook if needed
|
|
c.cache.Cache.SetWithHook(pnext, &ttl.Entry[int64, result[Value]]{
|
|
Expiry: c.expiry(),
|
|
Key: pnext,
|
|
Value: res,
|
|
}, func(_ int64, item *ttl.Entry[int64, result[Value]]) {
|
|
evict = func() { c.cache.Evict(item.Key, item.Value) }
|
|
})
|
|
|
|
return evict
|
|
}
|
|
|
|
//go:linkname runtime_nanotime runtime.nanotime
|
|
func runtime_nanotime() uint64
|
|
|
|
// expiry returns an the next expiry time to use for an entry,
|
|
// which is equivalent to time.Now().Add(ttl), or zero if disabled.
|
|
func (c *Cache[Value]) expiry() uint64 {
|
|
if ttl := c.cache.TTL; ttl > 0 {
|
|
return runtime_nanotime() +
|
|
uint64(c.cache.TTL)
|
|
}
|
|
return 0
|
|
}
|
|
|
|
type result[Value any] struct {
|
|
// keys accessible under
|
|
Keys cacheKeys
|
|
|
|
// cached value
|
|
Value Value
|
|
|
|
// cached error
|
|
Error error
|
|
}
|