cache

Documentation

Index

• Constants
• Variables
• func IdentifiableObjectKeyFunc[T any](object T) (string, error)
• func IdentifiableObjectLVSFunc[T any](object T, cardinality int) ([]string, error)
• func MustMakeMetrics(r prometheus.Registerer, m *cacheMetrics)
• func StoreObjectKeyFunc[T any](object StoreObject[T]) (string, error)
• type Cache
  • func New[T any](capacity int, keyFunc KeyFunc[T], opts ...Options[T]) (*Cache[T], error)
  • func (c Cache) Clear()
  • func (c *Cache[T]) Close() error
  • func (c *Cache[T]) Delete(object T) error
  • func (c *Cache[T]) Get(object T) (item T, exists bool, err error)
  • func (c *Cache[T]) GetByKey(key string) (T, bool, error)
  • func (c *Cache[T]) GetExpiration(object T) (time.Time, error)
  • func (c *Cache[T]) HasExpired(object T) (bool, error)
  • func (c Cache) ListKeys() ([]string, error)
  • func (c Cache) Resize(size int) (int, error)
  • func (c *Cache[T]) Set(object T) error
  • func (c *Cache[T]) SetExpiration(object T, expiration time.Time) error
• type CacheError
  • func (e *CacheError) Error() string
  • func (e *CacheError) Is(target error) bool
  • func (e *CacheError) Unwrap() error
• type CacheErrorReason
  • func (e CacheErrorReason) Error() string
• type Expirable
• type ExplicitKey
• type GetLvsFunc
• type IdentifiableObject
• type KeyFunc
• type LRU
  • func NewLRU[T any](capacity int, keyFunc KeyFunc[T], opts ...Options[T]) (*LRU[T], error)
  • func (c *LRU[T]) Delete(object T) error
  • func (c *LRU[T]) Get(object T) (item T, exists bool, err error)
  • func (c *LRU[T]) GetByKey(key string) (T, bool, error)
  • func (c *LRU[T]) ListKeys() ([]string, error)
  • func (c *LRU[T]) Resize(size int) (int, error)
  • func (c *LRU[T]) Set(object T) error
• type Options
  • func WithCleanupInterval[T any](interval time.Duration) Options[T]
  • func WithMetricsLabels[T any](labels []string, f GetLvsFunc[T]) Options[T]
  • func WithMetricsRegisterer[T any](r prometheus.Registerer) Options[T]
• type Store
• type StoreObject

Constants

const (
	// CacheEventTypeMiss is the event type for cache misses.
	CacheEventTypeMiss = "cache_miss"
	// CacheEventTypeHit is the event type for cache hits.
	CacheEventTypeHit = "cache_hit"
	// StatusSuccess is the status for successful cache requests.
	StatusSuccess = "success"
	// StatusFailure is the status for failed cache requests.
	StatusFailure = "failure"
)

Variables

var (
	ErrNotFound      = CacheErrorReason{"NotFound", "object not found"}
	ErrAlreadyExists = CacheErrorReason{"AlreadyRxists", "object already exists"}
	ErrCacheClosed   = CacheErrorReason{"CacheClosed", "cache is closed"}
	ErrCacheFull     = CacheErrorReason{"CacheFull", "cache is full"}
	ErrInvalidSize   = CacheErrorReason{"InvalidSize", "invalid size"}
	ErrInvalidKey    = CacheErrorReason{"InvalidKey", "invalid key"}
	ErrInvalidLabels = CacheErrorReason{"InvalidLabels", "invalid labels"}
)

var IdentifiableObjectLabels []string = []string{"name", "namespace", "kind"}

IdentifiableObjectLabels are the labels for an IdentifiableObject.

Functions

func IdentifiableObjectKeyFunc

func IdentifiableObjectKeyFunc[T any](object T) (string, error)

IdentifiableObjectKeyFunc is a convenient default KeyFunc which knows how to make keys from IdentifiableObject objects.

func IdentifiableObjectLVSFunc

func IdentifiableObjectLVSFunc[T any](object T, cardinality int) ([]string, error)

IdentifiableObjectLVSFunc returns the label's values for a metric for an IdentifiableObject.

func MustMakeMetrics

func MustMakeMetrics(r prometheus.Registerer, m *cacheMetrics)

MustMakeMetrics registers the metrics collectors in the given registerer.

func StoreObjectKeyFunc

func StoreObjectKeyFunc[T any](object StoreObject[T]) (string, error)

StoreObjectKeyFunc returns the key for a StoreObject.

Types

type Cache

type Cache[T any] struct {
	// contains filtered or unexported fields
}

Cache[T] is a thread-safe in-memory key/object store. It can be used to store objects with optional expiration. A function to extract the key from the object must be provided. Use the New function to create a new cache that is ready to use.

func New

func New[T any](capacity int, keyFunc KeyFunc[T], opts ...Options[T]) (*Cache[T], error)

New creates a new cache with the given configuration.

func (Cache) Clear

func (c Cache) Clear()

Clear all index from the cache. This reallocates the underlying array holding the index, so that the memory used by the index is reclaimed. A closed cache cannot be cleared.

func (*Cache[T]) Close

func (c *Cache[T]) Close() error

Close closes the cache. It also stops the expiration eviction process.

func (*Cache[T]) Delete

func (c *Cache[T]) Delete(object T) error

Delete an item from the cache. Does nothing if the key is not in the cache. It actually sets the item expiration to `now“, so that it will be deleted at the cleanup.

func (*Cache[T]) Get

func (c *Cache[T]) Get(object T) (item T, exists bool, err error)

Get an item from the cache. Returns the item or nil, and a bool indicating whether the key was found.

func (*Cache[T]) GetByKey

func (c *Cache[T]) GetByKey(key string) (T, bool, error)

GetByKey returns the object for the given key.

func (*Cache[T]) GetExpiration

func (c *Cache[T]) GetExpiration(object T) (time.Time, error)

GetExpiration returns the expiration for the given key. Returns zero if the key is not in the cache or the item has already expired.

func (*Cache[T]) HasExpired

func (c *Cache[T]) HasExpired(object T) (bool, error)

HasExpired returns true if the item has expired.

func (Cache) ListKeys

func (c Cache) ListKeys() ([]string, error)

ListKeys returns a slice of the keys in the cache.

func (Cache) Resize

func (c Cache) Resize(size int) (int, error)

Resize resizes the cache and returns the number of index removed. Size must be greater than zero.

func (*Cache[T]) Set

func (c *Cache[T]) Set(object T) error

Set an item in the cache, existing index will be overwritten. If the cache is full, Add will return an error.

func (*Cache[T]) SetExpiration

func (c *Cache[T]) SetExpiration(object T, expiration time.Time) error

SetExpiration sets the expiration for the given key.

type CacheError

type CacheError struct {
	Reason CacheErrorReason
	Err    error
}

func (*CacheError) Error

func (e *CacheError) Error() string

Error returns Err as a string, prefixed with the Reason to provide context.

func (*CacheError) Is

func (e *CacheError) Is(target error) bool

Is returns true if the Reason or Err equals target. It can be used to programmatically place an arbitrary Err in the context of the Cache:

err := &CacheError{Reason: ErrCacheFull, Err: errors.New("arbitrary resize error")}
errors.Is(err, ErrCacheFull)

func (*CacheError) Unwrap

func (e *CacheError) Unwrap() error

Unwrap returns the underlying Err.

type CacheErrorReason

type CacheErrorReason struct {
	// contains filtered or unexported fields
}

CacheErrorReason is a type that represents the reason for a cache error.

func (CacheErrorReason) Error

func (e CacheErrorReason) Error() string

Error gives a human-readable description of the error.

type Expirable

type Expirable[T any] interface {
	Store[T]
	// SetExpiration sets the expiration time for the object.
	SetExpiration(object T, expiresAt time.Time) error
	// GetExpiration returns the expiration time for the object in unix time.
	GetExpiration(object T) (time.Time, error)
	// HasExpired returns true if the object has expired.
	HasExpired(object T) (bool, error)
}

Expirable is an interface for a cache store that supports expiration.

type ExplicitKey

type ExplicitKey string

ExplicitKey can be passed to IdentifiableObjectKeyFunc if you have the key for the objectec but not the object itself.

type GetLvsFunc

type GetLvsFunc[T any] func(obj T, cardinality int) ([]string, error)

GetLvsFunc is a function that returns the label's values for a metric.

type IdentifiableObject

type IdentifiableObject struct {
	object.ObjMetadata
	// Object is the object that is being stored.
	Object any
}

IdentifiableObject is a wrapper for an object with its identifying metadata.

type KeyFunc

type KeyFunc[T any] func(object T) (string, error)

KeyFunc knows how to make a key from an object. Implementations should be deterministic.

type LRU

type LRU[T any] struct {
	// contains filtered or unexported fields
}

LRU is a thread-safe in-memory key/object store. All methods are safe for concurrent use. All operations are O(1). The hash map lookup is O(1) and so is the doubly linked list insertion/deletion.

The LRU is implemented as a doubly linked list, where the most recently accessed item is at the front of the list and the least recently accessed item is at the back. When an item is accessed, it is moved to the front of the list. When the cache is full, the least recently accessed item is removed from the back of the list.

                                  Cache
           ┌───────────────────────────────────────────────────┐
           │                                                   │
  empty    │     obj         obj          obj          obj     │    empty
┌───────┐  │  ┌───────┐   ┌───────┐     ┌───────┐   ┌───────┐  │  ┌───────┐
│       │  │  │       │   │       │ ... │       │   │       │  │  │       │
│ HEAD  │◄─┼─►│       │◄─►│       │◄───►│       │◄─►│       │◄─┼─►│ TAIL  │
│       │  │  │       │   │       │     │       │   │       │  │  │       │
└───────┘  │  └───────┘   └───────┘     └───────┘   └───────┘  │  └───────┘
           │                                                   │
           │                                                   │
           └───────────────────────────────────────────────────┘

A function to extract the key from the object must be provided. Use the NewLRU function to create a new cache that is ready to use.

func NewLRU

func NewLRU[T any](capacity int, keyFunc KeyFunc[T], opts ...Options[T]) (*LRU[T], error)

NewLRU creates a new LRU cache with the given capacity and keyFunc.

func (*LRU[T]) Delete

func (c *LRU[T]) Delete(object T) error

Delete removes a node from the list

func (*LRU[T]) Get

func (c *LRU[T]) Get(object T) (item T, exists bool, err error)

Get returns the given object from the cache. If the object is not in the cache, it returns false.

func (*LRU[T]) GetByKey

func (c *LRU[T]) GetByKey(key string) (T, bool, error)

GetByKey returns the object for the given key.

func (*LRU[T]) ListKeys

func (c *LRU[T]) ListKeys() ([]string, error)

ListKeys returns a list of keys in the cache.

func (*LRU[T]) Resize

func (c *LRU[T]) Resize(size int) (int, error)

Resize resizes the cache and returns the number of items removed.

func (*LRU[T]) Set

func (c *LRU[T]) Set(object T) error

Set an item in the cache, existing index will be overwritten.

type Options

type Options[T any] func(*storeOptions[T]) error

Options is a function that sets the store options.

func WithCleanupInterval

func WithCleanupInterval[T any](interval time.Duration) Options[T]

WithCleanupInterval sets the interval for the cache cleanup.

func WithMetricsLabels

func WithMetricsLabels[T any](labels []string, f GetLvsFunc[T]) Options[T]

WithMetricsLabels sets the extra labels for the cache metrics.

func WithMetricsRegisterer

func WithMetricsRegisterer[T any](r prometheus.Registerer) Options[T]

WithMetricsRegisterer sets the Prometheus registerer for the cache metrics.

type Store

type Store[T any] interface {
	// Set adds an object to the store.
	// It will overwrite the item if it already exists.
	Set(object T) error
	// Delete deletes an object from the store.
	Delete(object T) error
	// ListKeys returns a list of keys in the store.
	ListKeys() ([]string, error)
	// Get returns the object stored in the store.
	Get(object T) (item T, exists bool, err error)
	// GetByKey returns the object stored in the store by key.
	GetByKey(key string) (item T, exists bool, err error)
	// Resize resizes the store and returns the number of items removed.
	Resize(int) (int, error)
}

Store is an interface for a cache store. It is a generic version of the Kubernetes client-go cache.Store interface. See https://pkg.go.dev/k8s.io/client-go/tools/cache#Store The implementation should know how to extract a key from an object.

type StoreObject

type StoreObject[T any] struct {
	// Object is the object that is being stored.
	Object T
	// Key is the key for the object.
	Key string
}

StoreObject is a wrapper for an object with its identifying key. It is used to store objects in a Store. This helper is useful when the object does not have metadata to extract the key from. The supplied key can be retrieved with the StoreObjectKeyFunc. When the object has metadata, use IdentifiableObject instead if possible.