config.go

package sc

import (
	"time"
)

// CacheOption represents a single cache option.
// See other package-level functions which return CacheOption for more details.
type CacheOption func(c *cacheConfig)

type cacheConfig struct {
	enableStrictCoalescing bool
	backend                cacheBackendType
	capacity               int
	cleanupInterval        time.Duration
}

type cacheBackendType int

const (
	cacheBackendMap cacheBackendType = iota
	cacheBackendLRU
	cacheBackend2Q
)

func defaultConfig(ttl time.Duration) cacheConfig {
	cleanupInterval := 2 * ttl
	if ttl == 0 {
		cleanupInterval = 60 * time.Second
	}
	return cacheConfig{
		enableStrictCoalescing: false,
		backend:                cacheBackendMap,
		capacity:               0,
		cleanupInterval:        cleanupInterval,
	}
}

// WithMapBackend specifies to use the built-in map for storing cache items (the default).
//
// Note that this default map backend cannot have the maximum number of items configured,
// so it holds all values in memory until expired values are cleaned regularly
// at the interval specified by WithCleanupInterval.
//
// If your key's cardinality is high and if you would like to hard-limit the cache's memory usage,
// consider using other backends such as LRU backend.
//
// Initial capacity needs to be non-negative.
func WithMapBackend(initialCapacity int) CacheOption {
	return func(c *cacheConfig) {
		c.backend = cacheBackendMap
		c.capacity = initialCapacity
	}
}

// WithLRUBackend specifies to use LRU for storing cache items.
// Capacity needs to be greater than 0.
func WithLRUBackend(capacity int) CacheOption {
	return func(c *cacheConfig) {
		c.backend = cacheBackendLRU
		c.capacity = capacity
	}
}

// With2QBackend specifies to use 2Q cache for storing cache items.
// Capacity needs to be greater than 0.
func With2QBackend(capacity int) CacheOption {
	return func(c *cacheConfig) {
		c.backend = cacheBackend2Q
		c.capacity = capacity
	}
}

// EnableStrictCoalescing enables 'strict coalescing check' with a slight overhead. The check prevents Get() calls
// coming later in time to be coalesced with already stale response generated by a Get() call earlier in time.
//
// Ordinary cache users should not need this behavior.
//
// This is similar to 'automatically calling' (*Cache).Forget after a value is expired, but different in that
// it does not allow initiating new request until the current one finishes or (*Cache).Forget is explicitly called.
//
// Using this option, one may construct a 'throttler' / 'coalescer' not only of get requests but also of update requests.
//
// This is a generalization of so-called 'zero-time-cache', where the original zero-time-cache behavior is
// achievable with zero freshFor/ttl values.
// see also: https://qiita.com/methane/items/27ccaee5b989fb5fca72 (ja)
//
// ## Example with freshFor == 0 and ttl == 0
//
// 1st Get() call will return value from the first replaceFn call.
//
// 2nd Get() call will NOT return value from the first replaceFn call, since by the time 2nd Get() call is made,
// value from the first replaceFn call is already considered expired.
// Instead, 2nd Get() call will initiate the second replaceFn call, and will return that value.
// Without EnableStrictCoalescing option, 2nd Get() call will share the value from the first replaceFn call.
//
// In order to immediately initiate next replaceFn call without waiting for the previous replaceFn call to finish,
// use (*Cache).Forget or (*Cache).Purge.
//
// Similarly, 3rd and 4th Get() call will NOT return value from the second replaceFn call, but instead initiate
// the third replaceFn call.
//
// With EnableStrictCoalescing
//
//	Get() is called....: 1  2     3 4
//	returned value.....: 1  2     3 3
//	replaceFn is called: 1---->12---->23---->3
//
// Without EnableStrictCoalescing
//
//	Get() is called....: 1  2     3 4
//	returned value.....: 1  1     2 2
//	replaceFn is called: 1---->1  2---->2
//
// ## Example with freshFor == 1s and ttl == 1s
//
// 1st, 2nd, and 3rd Get() calls all return value from the first replaceFn call, since the value is considered fresh.
//
// 4th and 5th call do NOT return value from the first replaceFn call, since by the time these calls are made,
// value by the first replaceFn call is already considered expired.
// Instead, 4th (and 5th) call will initiate the second replaceFn call.
// Without EnableStrictCoalescing option, 4th call will share the value from the first replaceFn call,
// and 5th Get() call will initiate the second replaceFn call.
//
// With EnableStrictCoalescing:
//
//	Elapsed time (s)...: 0         1         2
//	Get() is called....: 1  2    3   4    5
//	returned value.....: 1  1    1   2    2
//	replaceFn is called: 1------------>12------------>2
//
// Without EnableStrictCoalescing:
//
//	Elapsed time (s)...: 0         1         2
//	Get() is called....: 1  2    3   4    5
//	returned value.....: 1  1    1   1    2
//	replaceFn is called: 1------------>1  2------------>2
func EnableStrictCoalescing() CacheOption {
	return func(c *cacheConfig) {
		c.enableStrictCoalescing = true
	}
}

// WithCleanupInterval specifies cleanup interval of expired items.
//
// Setting interval of 0 (or negative) will disable the cleaner.
// This means if you use non-evicting cache backend (that is, the default, built-in map backend),
// the cache keeps holding key-value pairs indefinitely.
// If cardinality of key is very large, this leads to memory leak.
//
// By default, a cleaner runs every once in 2x ttl (or every 60s if ttl == 0).
// Try tuning your cache size (and using non-map backend) before tuning this option.
// Using cleanup interval on a cache with many items may decrease the through-put,
// since the cleaner has to acquire the lock to iterate through all items.
func WithCleanupInterval(interval time.Duration) CacheOption {
	return func(c *cacheConfig) {
		c.cleanupInterval = interval
	}
}