lrucache

Documentation

Overview

Package lrucache provides in-memory cache with LRU eviction policy and Prometheus metrics.

Example

type User struct {
	ID   int
	Name string
}

// Make and register Prometheus metrics collector.
promMetrics := NewPrometheusMetricsWithOpts(PrometheusMetricsOpts{Namespace: "my_service_user"})
promMetrics.MustRegister()

// Make LRU cache for storing maximum 1000 entries
cache, err := New[string, User](1000, promMetrics)
if err != nil {
	log.Fatal(err)
}

// Add entries to cache.
cache.Add("user:1", User{1, "Alice"})
cache.Add("user:2", User{2, "Bob"})

// Get entries from cache.
if user, found := cache.Get("user:1"); found {
	fmt.Printf("%d, %s\n", user.ID, user.Name)
}
if user, found := cache.Get("user:2"); found {
	fmt.Printf("%d, %s\n", user.ID, user.Name)
}

Output:

1, Alice
2, Bob

Index

• type LRUCache
  • func New[K comparable, V any](maxEntries int, metricsCollector MetricsCollector) (*LRUCache[K, V], error)
  • func (c *LRUCache[K, V]) Add(key K, value V)
  • func (c *LRUCache[K, V]) Get(key K) (value V, ok bool)
  • func (c *LRUCache[K, V]) GetOrAdd(key K, valueProvider func() V) (value V, exists bool)
  • func (c *LRUCache[K, V]) Len() int
  • func (c *LRUCache[K, V]) Purge()
  • func (c *LRUCache[K, V]) Remove(key K) bool
  • func (c *LRUCache[K, V]) Resize(size int) (evicted int)
• type MetricsCollector
• type PrometheusMetrics
  • func NewPrometheusMetrics() *PrometheusMetrics
  • func NewPrometheusMetricsWithOpts(opts PrometheusMetricsOpts) *PrometheusMetrics
  • func (pm *PrometheusMetrics) AddEvictions(n int)
  • func (pm *PrometheusMetrics) IncHits()
  • func (pm *PrometheusMetrics) IncMisses()
  • func (pm *PrometheusMetrics) MustCurryWith(labels prometheus.Labels) *PrometheusMetrics
  • func (pm *PrometheusMetrics) MustRegister()
  • func (pm *PrometheusMetrics) SetAmount(amount int)
  • func (pm *PrometheusMetrics) Unregister()
• type PrometheusMetricsOpts

Examples

• Package

Types

type LRUCache

type LRUCache[K comparable, V any] struct {
	// contains filtered or unexported fields
}

LRUCache represents an LRU cache with eviction mechanism and Prometheus metrics.

func New

func New[K comparable, V any](maxEntries int, metricsCollector MetricsCollector) (*LRUCache[K, V], error)

New creates a new LRUCache with the provided maximum number of entries.

func (*LRUCache[K, V]) Add

func (c *LRUCache[K, V]) Add(key K, value V)

Add adds a value to the cache with the provided key and type. If the cache is full, the oldest entry will be removed.

func (*LRUCache[K, V]) Get

func (c *LRUCache[K, V]) Get(key K) (value V, ok bool)

Get returns a value from the cache by the provided key and type.

func (*LRUCache[K, V]) GetOrAdd

func (c *LRUCache[K, V]) GetOrAdd(key K, valueProvider func() V) (value V, exists bool)

func (*LRUCache[K, V]) Len

func (c *LRUCache[K, V]) Len() int

Len returns the number of items in the cache.

func (*LRUCache[K, V]) Purge

func (c *LRUCache[K, V]) Purge()

Purge clears the cache. Keep in mind that this method does not reset the cache size and does not reset Prometheus metrics except for the total number of entries. All removed entries will not be counted as evictions.

func (*LRUCache[K, V]) Remove

func (c *LRUCache[K, V]) Remove(key K) bool

Remove removes a value from the cache by the provided key and type.

func (*LRUCache[K, V]) Resize

func (c *LRUCache[K, V]) Resize(size int) (evicted int)

Resize changes the cache size and returns the number of evicted entries.

type MetricsCollector

type MetricsCollector interface {
	// SetAmount sets the total number of entries in the cache.
	SetAmount(int)

	// IncHits increments the total number of successfully found keys in the cache.
	IncHits()

	// IncMisses increments the total number of not found keys in the cache.
	IncMisses()

	// AddEvictions increments the total number of evicted entries.
	AddEvictions(int)
}

MetricsCollector represents a collector of metrics to analyze how (effectively or not) cache is used.

type PrometheusMetrics

type PrometheusMetrics struct {
	EntriesAmount  *prometheus.GaugeVec
	HitsTotal      *prometheus.CounterVec
	MissesTotal    *prometheus.CounterVec
	EvictionsTotal *prometheus.CounterVec
}

PrometheusMetrics represents a Prometheus metrics for the cache.

func NewPrometheusMetrics

func NewPrometheusMetrics() *PrometheusMetrics

NewPrometheusMetrics creates a new instance of PrometheusMetrics with default options.

func NewPrometheusMetricsWithOpts

func NewPrometheusMetricsWithOpts(opts PrometheusMetricsOpts) *PrometheusMetrics

NewPrometheusMetricsWithOpts creates a new instance of PrometheusMetrics with the provided options.

func (*PrometheusMetrics) AddEvictions

func (pm *PrometheusMetrics) AddEvictions(n int)

AddEvictions increments the total number of evicted entries.

func (*PrometheusMetrics) IncHits

func (pm *PrometheusMetrics) IncHits()

IncHits increments the total number of successfully found keys in the cache.

func (*PrometheusMetrics) IncMisses

func (pm *PrometheusMetrics) IncMisses()

IncMisses increments the total number of not found keys in the cache.

func (*PrometheusMetrics) MustCurryWith

func (pm *PrometheusMetrics) MustCurryWith(labels prometheus.Labels) *PrometheusMetrics

MustCurryWith curries the metrics collector with the provided labels.

func (*PrometheusMetrics) MustRegister

func (pm *PrometheusMetrics) MustRegister()

MustRegister does registration of metrics collector in Prometheus and panics if any error occurs.

func (*PrometheusMetrics) SetAmount

func (pm *PrometheusMetrics) SetAmount(amount int)

SetAmount sets the total number of entries in the cache.

func (*PrometheusMetrics) Unregister

func (pm *PrometheusMetrics) Unregister()

Unregister cancels registration of metrics collector in Prometheus.

type PrometheusMetricsOpts

type PrometheusMetricsOpts struct {
	// Namespace is a namespace for metrics. It will be prepended to all metric names.
	Namespace string

	// ConstLabels is a set of labels that will be applied to all metrics.
	ConstLabels prometheus.Labels

	// CurriedLabelNames is a list of label names that will be curried with the provided labels.
	// See PrometheusMetrics.MustCurryWith method for more details.
	// Keep in mind that if this list is not empty,
	// PrometheusMetrics.MustCurryWith method must be called further with the same labels.
	// Otherwise, the collector will panic.
	CurriedLabelNames []string
}

PrometheusMetricsOpts represents options for PrometheusMetrics.