warmer

README

Warmer

Warmer is a Go package that provides intelligent cache warming functionality. It tracks key access patterns and proactively warms up frequently accessed keys in your cache to improve application performance.

Features

• Automatic cache warming based on key access patterns
• Configurable warming intervals and batch sizes
• Statistical tracking of key access rates
• Support for different rate intervals (1, 5, or 15 minutes)
• Customizable error handling and monitoring callbacks
• Generic implementation supporting any comparable key type and any value type
• Thread-safe operations

Requirements

• Go 1.18 or higher (required for generics support)

Installation

go get github.com/n-r-w/warmer

Quick Start

Here's a simple example of how to use the warmer package:

package main

import (
    "context"
    "time"
    "github.com/n-r-w/warmer"
)

func main() {
    // Create warmer configuration
    config := warmer.Config[string]{
        Interval:     time.Second * 5,     // Warm cache every 5 seconds
        BatchSize:    100,                 // Process 100 keys per batch
        MaxStatsSize: 1000,               // Keep stats for 1000 keys
        RateInterval: warmer.RateInterval15, // Use 15-minute rate interval
    }

    // Create warmer instance
    w := warmer.New(
        // Function to get data from DB
        func(ctx context.Context, key string) (string, error) {
            return getFromDB(key)
        },
        // Function to set data in cache
        func(ctx context.Context, key string, value string) error {
            return setToCache(key, value)
        },
        config,
    )

    // Start the warmer
    ctx := context.Background()
    w.Start(ctx)

    // Track key updates in your application
    w.TrackUpdate(ctx, "key1", 1)

    // Stop the warmer when done
    w.Stop()
}

Configuration

The Config struct provides the following configuration options:

Parameter	Description	Default
Interval	Duration between warming cycles	1 minute
BatchSize	Number of keys to warm up in one cycle	MaxStatsSize/10
MaxStatsSize	Maximum number of keys to track	100000
RateInterval	Update rate interval (1, 5, or 15 minutes)	15 minutes
OnKeyTrack	Callback for key access tracking	nil
OnDBError	Callback for database read errors	nil
OnCacheError	Callback for cache write errors	nil
OnWarmTrack	Callback for successful key warming	nil

Note: The default BatchSize is automatically calculated as one-tenth of MaxStatsSize. For example, with the default MaxStatsSize of 100000, the default BatchSize would be 10000.

Callbacks

The warmer package provides several callback functions for monitoring and debugging:

config := warmer.Config[string]{
    OnWarmTrack: func(ctx context.Context, key string, rate float64) {
        log.Printf("Key warmed: %s, rate: %.2f", key, rate)
    },
    OnKeyTrack: func(ctx context.Context, key string, rate float64) {
        log.Printf("Key tracked: %s, rate: %.2f", key, rate)
    },
    OnDBError: func(ctx context.Context, key string, err error) {
        log.Printf("DB error for key %s: %v", key, err)
    },
    OnCacheError: func(ctx context.Context, key string, err error) {
        log.Printf("Cache error for key %s: %v", key, err)
    },
}

How It Works

1. The warmer tracks key access patterns through the TrackUpdate method
2. It maintains statistics about key access rates using meters
3. Periodically (based on the configured interval), it selects the most frequently accessed keys using Roulette Wheel Selection algorithm:
   • Each key's probability of being selected is proportional to its access rate
   • This probabilistic approach ensures diversity in cache warming while favoring frequently accessed keys
4. These keys are then proactively loaded from the database and stored in the cache
5. The process continues until the warmer is stopped

Thread Safety

The warmer package is thread-safe and can be safely used from multiple goroutines.

License

This project is released under the MIT License.

Documentation

Index

• Constants
• type Config
  • func DefaultConfig[K comparable]() Config[K]
• type GetFromDBFunc
• type OnErrorFunc
• type OnKeyTrackFunc
• type OnKeyWarmFunc
• type RateIntervalType
• type SetToCacheFunc
• type Warmer
  • func New[K comparable, V any](getFromDB GetFromDBFunc[K, V], setToCache SetToCacheFunc[K, V], ...) *Warmer[K, V]
  • func (w *Warmer[K, V]) Start(ctx context.Context)
  • func (w *Warmer[K, V]) Stop()
  • func (w *Warmer[K, V]) TrackUpdate(ctx context.Context, key K, count int64)

Constants

const (
	// DefaultMaxStatsSize defines the default maximum size of statistics.
	DefaultMaxStatsSize = 100000
	// DefaultBatchSize defines the default size of the key batch for warming.
	DefaultBatchSize = DefaultMaxStatsSize / defaultBatchToMaxMultiplier
	// DefaultRateInterval defines the default update rate interval.
	DefaultRateInterval = RateInterval15
)

Types

type Config

type Config[K comparable] struct {
	// Interval between warming cycles.
	Interval time.Duration

	// Number of keys to warm up in one cycle.
	// If 0, the default value is used (MaxStatsSize/10).
	BatchSize int

	// MaxStatsSize defines the maximum number of records in statistics.
	// When this value is exceeded, old records will be removed.
	// If 0, the default value is used (100000).
	MaxStatsSize int

	// RateInterval defines the update rate interval.
	// If 0, the default value is used (15 minutes).
	RateInterval RateIntervalType

	// Callback for collecting key statistics.
	// Called on each key track.
	OnKeyTrack OnKeyTrackFunc[K]

	// Callback for collecting database read error statistics.
	// Called on each read error.
	OnDBError OnErrorFunc[K]

	// Callback for collecting cache write error statistics.
	// Called on each write error.
	OnCacheError OnErrorFunc[K]

	// OnWarmTrack is called when a key is warmed up.
	OnWarmTrack OnKeyWarmFunc[K]
}

Config contains Warmer settings.

func DefaultConfig

func DefaultConfig[K comparable]() Config[K]

DefaultConfig returns the default configuration.

type GetFromDBFunc

type GetFromDBFunc[K comparable, V any] func(ctx context.Context, key K) (V, error)

GetFromDBFunc defines a function for retrieving an object from the database.

type OnErrorFunc

type OnErrorFunc[K comparable] func(ctx context.Context, key K, err error)

OnErrorFunc defines a function for handling errors.

type OnKeyTrackFunc

type OnKeyTrackFunc[K comparable] func(ctx context.Context, key K, rate float64)

OnKeyTrackFunc defines a function for handling key tracking.

type OnKeyWarmFunc

type OnKeyWarmFunc[K comparable] func(ctx context.Context, key K, rate float64)

OnKeyWarmFunc defines a function for handling key tracking.

type RateIntervalType

type RateIntervalType int

RateIntervalType defines the update rate interval.

const (
	RateInterval1  RateIntervalType = iota // RateInterval1 1 minute
	RateInterval5                          // RateInterval5 5 minutes
	RateInterval15                         // RateInterval15 15 minutes
)

type SetToCacheFunc

type SetToCacheFunc[K comparable, V any] func(ctx context.Context, key K, value V) error

SetToCacheFunc defines a function for saving an object to the cache.

type Warmer

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

Warmer provides cache warming functionality.

func New

func New[K comparable, V any](
	getFromDB GetFromDBFunc[K, V], setToCache SetToCacheFunc[K, V], config Config[K],
) *Warmer[K, V]

New creates a new warmer instance with specified database and cache access functions.

func (*Warmer[K, V]) Start

func (w *Warmer[K, V]) Start(ctx context.Context)

Start starts the cache warming process.

func (*Warmer[K, V]) Stop

func (w *Warmer[K, V]) Stop()

Stop stops the cache warming process.

func (*Warmer[K, V]) TrackUpdate

func (w *Warmer[K, V]) TrackUpdate(ctx context.Context, key K, count int64)

TrackUpdate registers a key update. count - number of updates