cache

package
v1.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 29, 2025 License: MIT Imports: 8 Imported by: 0

README

Cache

Overview

The Cache component provides a generic in-memory cache implementation for storing and retrieving data with configurable Time-To-Live (TTL), size limits, and automatic cleanup.

Features

  • Generic Implementation: Works with any data type
  • TTL Support: Automatically expires items after a configurable time
  • Size Limiting: Limits the maximum number of items in the cache
  • Automatic Cleanup: Periodically removes expired items
  • Thread-Safe: Safe for concurrent use

Installation

go get github.com/abitofhelp/servicelib/cache

Quick Start

See the Basic Usage example for a complete, runnable example of how to use the cache component.

Configuration

See the Custom Configuration example for a complete, runnable example of how to configure the cache component.

API Documentation

Core Types

The cache component provides several core types for implementing caching functionality.

Cache

The main type that implements the cache functionality.

type Cache[T any] struct {
    // Fields
}
Config

Configuration for the Cache.

type Config struct {
    Enabled        bool
    TTL            time.Duration
    MaxSize        int
    PurgeInterval  time.Duration
}
Item

Represents an item in the cache.

type Item struct {
    Value      interface{}
    Expiration int64
}
Key Methods

The cache component provides several key methods for working with the cache.

Set

Sets a value in the cache with the default TTL.

func (c *Cache[T]) Set(ctx context.Context, key string, value T)
SetWithTTL

Sets a value in the cache with a custom TTL.

func (c *Cache[T]) SetWithTTL(ctx context.Context, key string, value T, ttl time.Duration)
Get

Gets a value from the cache.

func (c *Cache[T]) Get(ctx context.Context, key string) (T, bool)
Delete

Deletes a value from the cache.

func (c *Cache[T]) Delete(ctx context.Context, key string)
Clear

Clears all values from the cache.

func (c *Cache[T]) Clear(ctx context.Context)

Examples

For complete, runnable examples, see the following directories in the EXAMPLES directory:

Best Practices

  1. Use Appropriate TTL: Set appropriate TTL values based on your data's freshness requirements
  2. Limit Cache Size: Set a reasonable maximum size to prevent memory issues
  3. Handle Cache Misses: Always handle the case when an item is not found in the cache
  4. Use WithCache Helper: Use the WithCache helper function for common cache patterns
  5. Shutdown Properly: Call Shutdown() when you're done with the cache to stop background cleanup

Troubleshooting

Common Issues
Cache Items Expiring Too Quickly

If cache items are expiring too quickly, check that your TTL value is appropriate for your use case.

Cache Using Too Much Memory

If the cache is using too much memory, reduce the MaxSize configuration parameter.

  • Logging - Logging for cache operations
  • Telemetry - Telemetry for cache operations

Contributing

Contributions to this component are welcome! Please see the Contributing Guide for more information.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Overview

Package cache provides functionality for caching frequently accessed data.

This package implements a simple in-memory cache with expiration.

Package cache provides functionality for caching frequently accessed data.

This package implements a generic in-memory cache with expiration, supporting various eviction strategies and thread-safe operations. It is designed to be flexible and easy to use, with configurable time-to-live (TTL) for cache items, maximum size limits, and automatic cleanup of expired items.

Key features:

  • Generic implementation that works with any data type
  • Configurable item expiration (TTL)
  • Maximum size limits with various eviction strategies
  • Thread-safe operations for concurrent access
  • Automatic cleanup of expired items
  • Integration with OpenTelemetry for tracing
  • Comprehensive logging of cache operations

The package provides several main components:

  • Cache: A generic in-memory cache with expiration
  • Config: Configuration for cache behavior
  • Options: Additional options for logging and tracing
  • EvictionStrategy: Different strategies for evicting items when the cache is full

Example usage: 

// Create a cache for string values with default configuration
cache := cache.NewCache[string](cache.DefaultConfig(), cache.DefaultOptions())

// Store a value in the cache
cache.Set(ctx, "key1", "value1")

// Retrieve a value from the cache
value, found := cache.Get(ctx, "key1")
if found {
    fmt.Println("Value:", value)
}

// Store a value with a custom TTL
cache.SetWithTTL(ctx, "key2", "value2", 5*time.Minute)

// Delete a value from the cache
cache.Delete(ctx, "key1")

// Execute a function with caching
result, err := cache.WithCache(ctx, "key3", func(ctx context.Context) (string, error) {
    // Expensive operation to generate the value
    return "computed-value", nil
}, 10*time.Minute)

The cache package is designed to be used as a dependency by other packages in the application, providing a consistent caching interface throughout the codebase.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func WithCache 

func WithCache[T any](ctx context.Context, cache *Cache[T], key string, fn func(ctx context.Context) (T, error)) (T, error)

WithCache executes a function with caching. This utility function implements a caching middleware pattern. It first tries to retrieve the value from the cache using the provided key. If the value is found in the cache, it is returned immediately without executing the function. If the value is not found, the function is executed, and its result is stored in the cache before being returned.

This pattern is useful for expensive operations that are called frequently with the same parameters, such as database queries or API calls. The cached results use the default TTL configured for the cache. For custom TTL, use WithCacheTTL instead.

If the cache is nil (which happens when the cache is disabled), the function is executed directly without any caching.

Type Parameters:

  • T: The type of value to be cached and returned by the function.

Parameters:

  • ctx: The context for the operation, which can be used for tracing and cancellation.
  • cache: The cache instance to use for storing and retrieving values.
  • key: The key under which to store and retrieve the value in the cache.
  • fn: The function to execute if the value is not found in the cache.

Returns:

  • T: The value retrieved from the cache or returned by the function.
  • error: An error if the function execution fails, or nil if successful.

func WithCacheTTL 

func WithCacheTTL[T any](ctx context.Context, cache *Cache[T], key string, ttl time.Duration, fn func(ctx context.Context) (T, error)) (T, error)

WithCacheTTL executes a function with caching and a custom time-to-live. This utility function is similar to WithCache but allows specifying a custom TTL for the cached result. It first tries to retrieve the value from the cache using the provided key. If the value is found in the cache, it is returned immediately without executing the function. If the value is not found, the function is executed, and its result is stored in the cache with the specified TTL before being returned.

This pattern is useful for expensive operations that are called frequently with the same parameters, such as database queries or API calls. The custom TTL allows for fine-grained control over how long results should be cached, which can be useful for data with different freshness requirements.

If the cache is nil (which happens when the cache is disabled), the function is executed directly without any caching.

Type Parameters:

  • T: The type of value to be cached and returned by the function.

Parameters:

  • ctx: The context for the operation, which can be used for tracing and cancellation.
  • cache: The cache instance to use for storing and retrieving values.
  • key: The key under which to store and retrieve the value in the cache.
  • ttl: The time-to-live duration for the cached value.
  • fn: The function to execute if the value is not found in the cache.

Returns:

  • T: The value retrieved from the cache or returned by the function.
  • error: An error if the function execution fails, or nil if successful.

Types

type Cache 

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

Cache is a generic in-memory cache with expiration. It provides thread-safe operations for storing and retrieving values of any type, with automatic expiration and cleanup of expired items. The cache supports configurable size limits with eviction strategies, and integrates with OpenTelemetry for tracing and monitoring.

Cache is implemented as a generic type, allowing it to store values of any type while maintaining type safety.

func NewCache 

func NewCache[T any](config Config, options Options) *Cache[T]

NewCache creates a new cache with the given configuration and options. It initializes the cache with the specified parameters and starts a background goroutine to periodically clean up expired items. If the cache is disabled (config.Enabled is false), it returns nil and no cache operations will be performed.

The function uses the provided logger and tracer from options, or creates no-op versions if they are nil. It also logs the initialization process, including the cache name, TTL, maximum size, and purge interval.

Type Parameters:

  • T: The type of values to be stored in the cache.

Parameters:

  • config: The configuration parameters for the cache.
  • options: Additional options for the cache, such as logging and tracing.

Returns:

  • *Cache[T]: A new cache instance configured according to the provided parameters, or nil if the cache is disabled.

func (*Cache[T]) Clear 

func (c *Cache[T]) Clear(ctx context.Context)

Clear removes all items from the cache. This method removes all items from the cache, effectively resetting it to an empty state. It creates a new empty map to replace the existing items map, allowing the garbage collector to reclaim the memory used by the old items.

This method is thread-safe and can be called concurrently from multiple goroutines. If the cache is nil (which happens when the cache is disabled), this method is a no-op.

Parameters:

  • ctx: The context for the operation, which can be used for tracing and cancellation.

func (*Cache[T]) Delete 

func (c *Cache[T]) Delete(ctx context.Context, key string)

Delete removes an item from the cache. This method removes the item with the specified key from the cache, if it exists. If the key doesn't exist in the cache, this method is a no-op.

This method is thread-safe and can be called concurrently from multiple goroutines. If the cache is nil (which happens when the cache is disabled), this method is a no-op.

Parameters:

  • ctx: The context for the operation, which can be used for tracing and cancellation.
  • key: The key of the item to remove from the cache.

func (*Cache[T]) Get 

func (c *Cache[T]) Get(ctx context.Context, key string) (T, bool)

Get retrieves an item from the cache. It returns the value and a boolean indicating whether the value was found. If the key doesn't exist or the item has expired, the zero value of type T and false are returned.

This method is thread-safe and can be called concurrently from multiple goroutines. If the cache is nil (which happens when the cache is disabled), this method returns the zero value of type T and false.

Parameters:

  • ctx: The context for the operation, which can be used for tracing and cancellation.
  • key: The key to look up in the cache.

Returns:

  • T: The value associated with the key, or the zero value of type T if not found.
  • bool: true if the key was found and the item hasn't expired, false otherwise.

func (*Cache[T]) Set 

func (c *Cache[T]) Set(ctx context.Context, key string, value T)

Set adds an item to the cache with the default expiration time. The item will be stored in the cache until it expires or is explicitly deleted. If the cache is full and the key doesn't already exist, an existing item will be evicted according to the cache's eviction strategy.

This method is thread-safe and can be called concurrently from multiple goroutines. If the cache is nil (which happens when the cache is disabled), this method is a no-op.

Parameters:

  • ctx: The context for the operation, which can be used for tracing and cancellation.
  • key: The key under which to store the value.
  • value: The value to store in the cache.

func (*Cache[T]) SetWithTTL 

func (c *Cache[T]) SetWithTTL(ctx context.Context, key string, value T, ttl time.Duration)

SetWithTTL adds an item to the cache with a custom expiration time. This method works like Set but allows specifying a custom time-to-live (TTL) for the item, overriding the default TTL configured for the cache.

The item will be stored in the cache until it expires according to the provided TTL or is explicitly deleted. If the cache is full and the key doesn't already exist, an existing item will be evicted according to the cache's eviction strategy.

This method is thread-safe and can be called concurrently from multiple goroutines. If the cache is nil (which happens when the cache is disabled), this method is a no-op.

Parameters:

  • ctx: The context for the operation, which can be used for tracing and cancellation.
  • key: The key under which to store the value.
  • value: The value to store in the cache.
  • ttl: The time-to-live duration for this specific item.

func (*Cache[T]) Shutdown 

func (c *Cache[T]) Shutdown()

Shutdown stops the cleanup timer and gracefully shuts down the cache. This method should be called when the cache is no longer needed to ensure that the background cleanup goroutine is properly terminated. It sends a signal to the cleanup goroutine to stop and logs the shutdown process.

This method is safe to call multiple times and from multiple goroutines. If the cache is nil (which happens when the cache is disabled), this method is a no-op.

It's recommended to call this method when the application is shutting down to prevent goroutine leaks and ensure proper resource cleanup.

func (*Cache[T]) Size 

func (c *Cache[T]) Size() int

Size returns the number of items in the cache. This method counts all items currently in the cache, including those that may have expired but haven't been removed by the cleanup process yet. For an accurate count of non-expired items, you would need to implement a custom counting method.

This method is thread-safe and can be called concurrently from multiple goroutines. If the cache is nil (which happens when the cache is disabled), this method returns 0.

Returns:

  • int: The number of items currently in the cache.

type Config 

type Config struct {
	// Enabled determines if the cache is enabled.
	// If set to false, cache operations become no-ops.
	Enabled bool

	// TTL is the default time-to-live for cache items.
	// Items older than this duration will be automatically removed during cleanup.
	TTL time.Duration

	// MaxSize is the maximum number of items in the cache.
	// When this limit is reached, new items will cause old items to be evicted.
	MaxSize int

	// PurgeInterval is the interval at which expired items are purged.
	// A background goroutine runs at this interval to remove expired items.
	PurgeInterval time.Duration
}

Config contains cache configuration parameters. It defines the behavior of the cache, including whether it's enabled, how long items are kept, the maximum size, and how often cleanup occurs.

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns a default cache configuration with reasonable values. The default configuration includes:

  • Enabled: true (cache is enabled)
  • TTL: 5 minutes (items expire after 5 minutes)
  • MaxSize: 1000 (maximum of 1000 items in the cache)
  • PurgeInterval: 1 minute (expired items are purged every minute)

Returns:

  • A Config instance with default values.

func (Config) WithEnabled 

func (c Config) WithEnabled(enabled bool) Config

WithEnabled sets whether the cache is enabled. If enabled is set to false, cache operations become no-ops.

Parameters:

  • enabled: A boolean indicating whether the cache should be enabled.

Returns:

  • A new Config instance with the updated Enabled value.

func (Config) WithMaxSize 

func (c Config) WithMaxSize(maxSize int) Config

WithMaxSize sets the maximum number of items in the cache. When this limit is reached, new items will cause old items to be evicted. If a non-positive value is provided, it will be set to 1.

Parameters:

  • maxSize: The maximum number of items allowed in the cache.

Returns:

  • A new Config instance with the updated MaxSize value.

func (Config) WithPurgeInterval 

func (c Config) WithPurgeInterval(purgeInterval time.Duration) Config

WithPurgeInterval sets the interval at which expired items are purged. A background goroutine runs at this interval to remove expired items. If a non-positive value is provided, it will be set to 1 millisecond.

Parameters:

  • purgeInterval: The interval between purge operations.

Returns:

  • A new Config instance with the updated PurgeInterval value.

func (Config) WithTTL 

func (c Config) WithTTL(ttl time.Duration) Config

WithTTL sets the default time-to-live for cache items. This determines how long items remain in the cache before they expire. If a non-positive value is provided, it will be set to 1 millisecond.

Parameters:

  • ttl: The time-to-live duration for cache items.

Returns:

  • A new Config instance with the updated TTL value.

type EvictionStrategy 

type EvictionStrategy int

EvictionStrategy defines the strategy for evicting items when the cache is full. It determines which items are removed when the cache reaches its maximum size and a new item needs to be added. 

const (
	// LRU evicts the least recently used item.
	// This strategy removes items that haven't been accessed for the longest time,
	// which is often the most efficient approach for many caching scenarios.
	LRU EvictionStrategy = iota

	// LFU evicts the least frequently used item.
	// This strategy removes items that have been accessed the fewest times,
	// which can be beneficial when access frequency is more important than recency.
	LFU

	// FIFO evicts the first item added to the cache.
	// This strategy implements a simple first-in, first-out queue,
	// removing the oldest items regardless of how often they've been accessed.
	FIFO

	// Random evicts a random item.
	// This strategy provides a simple and computationally inexpensive approach
	// that can work well when access patterns are unpredictable.
	Random
)

type Item 

type Item[T any] struct {
	// Value is the cached data of type T
	Value T
	// Expiration is the Unix timestamp in nanoseconds when this item expires
	Expiration int64
}

Item represents a cached item with its value and expiration time. It is a generic struct that can hold any type of value along with its expiration timestamp.

type Options 

type Options struct {
	// Logger is used for logging cache operations.
	// If nil, a no-op logger will be used.
	Logger *logging.ContextLogger

	// Tracer is used for tracing cache operations.
	// It provides integration with OpenTelemetry for distributed tracing.
	Tracer telemetry.Tracer

	// Name is the name of the cache.
	// This is useful for identifying the cache in logs and traces,
	// especially when multiple caches are used in the same application.
	Name string
}

Options contains additional options for the cache. These options are not directly related to the cache behavior itself, but provide additional functionality like logging, tracing, and identification.

func DefaultOptions 

func DefaultOptions() Options

DefaultOptions returns default options for cache operations. The default options include:

  • No logger (a no-op logger will be used)
  • A no-op tracer (no OpenTelemetry integration)
  • Name: "default"

Returns:

  • An Options instance with default values.

func (Options) WithLogger 

func (o Options) WithLogger(logger *logging.ContextLogger) Options

WithLogger sets the logger for the cache. The logger is used to log cache operations, such as initialization, evictions, and shutdown events.

Parameters:

  • logger: A ContextLogger instance for logging cache operations.

Returns:

  • A new Options instance with the updated Logger value.

func (Options) WithName 

func (o Options) WithName(name string) Options

WithName sets the name of the cache. The name is used to identify the cache in logs and traces, which is especially useful when multiple caches are used in the same application.

Parameters:

  • name: A string identifier for the cache.

Returns:

  • A new Options instance with the updated Name value.

func (Options) WithOtelTracer 

func (o Options) WithOtelTracer(tracer trace.Tracer) Options

WithOtelTracer returns Options with an OpenTelemetry tracer. This allows users to opt-in to OpenTelemetry tracing if they need it. The tracer is used to create spans for cache operations, which can be viewed in a distributed tracing system.

Parameters:

  • tracer: An OpenTelemetry trace.Tracer instance.

Returns:

  • A new Options instance with the provided OpenTelemetry tracer.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.