Documentation
¶
Overview ¶
Package shardlookup provides primitives to let shards lookup objects regardless of if they are on logical clusters on the local shard or in logical clusters on remote shards.
When to use shardlookup vs the cache server ¶
In general using shardlookup should be the first approach and the cache server should only be used when necessary.
The cache server replicates resources across all shards - meaning shards connect to it and run informers with watches on it. This is very expensive and will only get heavier as the kcp instance grows (since the bigger the instance is the more objects are replicated into the cache server).
As a rule of thumb:
- Use cache server if the objects are required so frequently that a ttl cache would cause more load
- Use cache server if event-driven behaviour is required
- Use shardlookup in all other cases
Index ¶
Constants ¶
const ( // DefaultSuccessTTL is the default TTL to cache a successful lookup. DefaultSuccessTTL = 1 * time.Minute // DefaultFailureTTL is the default TTL to cache a failed lookup. DefaultFailureTTL = 10 * time.Second )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Lookup ¶
type Lookup[V any] struct { // contains filtered or unexported fields }
Lookup is a simple wrapper to abstract to local-or-fetch logic into clean functions.
func NewLookup ¶
func NewLookup[V any]( cache *TTLCache[V], isLocal func(clusterName logicalcluster.Name, namespace, name string) bool, local func(clusterName logicalcluster.Name, namespace, name string) (V, error), fetch func(clusterName logicalcluster.Name, namespace, name string) (V, error), ) *Lookup[V]
NewLookup creates a new Lookup backed by the given TTLCache. The TTLCache is used to cache objects and synchronize requests.
isLocal determines if the key should be served from the local callback. local serves keys that are on the local shard, typically from an informer lister. fetch retrieves the value from a remote shard, typically via an API client.
type TTLCache ¶
type TTLCache[V any] struct { // contains filtered or unexported fields }
TTLCache caches objects in a TTL cache and synchronizes concurrent hits on the same key. Keys are strings, typically constructed via kcpcache.ToClusterAwareKey.
func NewTTLCacheWithOptions ¶
func NewTTLCacheWithOptions[V any](opts TTLOptions) *TTLCache[V]
NewTTLCacheWithOptions creates a new Cache with the given TTLOptions.
func (*TTLCache[V]) Get ¶
Get returns the value for key. If the key is cached within the TTL the cached value is returned but the TTL is not refreshed to prevent frequently used items from living forever. If the key is not cached or is expired the value is retrieved using the provided function and cached.
func (*TTLCache[V]) OnEviction ¶
func (c *TTLCache[V]) OnEviction(fn func(value V)) func()
OnEviction registers a callback that is called when an entry is evicted from the cache. The callback runs on a separate goroutine. The returned function can be called to unsubscribe.
func (*TTLCache[V]) Start ¶
func (c *TTLCache[V]) Start()
Start begins the background goroutine that evicts expired entries.
Running Start is not required for the TTLCache to function correctly, however not starting it will cause the cache to accrue stale items in memory until the process exits. Saving this goroutine can be a tradeoff if the amount of possible keys is known to be finite and low.
func (*TTLCache[V]) StartWithContext ¶
StartWithContext calls .Start and calls .Stop when the context is canceled.
type TTLOptions ¶
type TTLOptions struct {
// SuccessTTL is the TTL to cache a successful lookup. Defaults to DefaultSuccessTTL.
SuccessTTL time.Duration
// FailureTTL is the TTL to cache a failed lookup. Defaults to DefaultFailureTTL.
FailureTTL time.Duration
}
TTLOptions contains options for the TTLCache.
Source Files