Raxol.Terminal.Graphics.ImageCache (Raxol v2.0.1)

View Source

High-performance caching system for processed images and graphics data.

Provides intelligent caching with:

  • LRU (Least Recently Used) eviction policy
  • Memory usage monitoring and limits
  • Cache key generation and management
  • Batch cache operations
  • Cache warming and preloading
  • Performance metrics and monitoring

Cache Strategies

  • Memory Cache - Fast in-memory storage for frequently accessed images
  • Disk Cache - Persistent storage for large images and processed variants
  • Distributed Cache - Shared cache across multiple processes (future)

Usage

# Start cache server
{:ok, _pid} = ImageCache.start_link(%{
  max_memory: 100_000_000,  # 100MB
  max_entries: 1000,
  ttl: 3600  # 1 hour
})

# Cache processed image
:ok = ImageCache.put("image_key_300x200", processed_image_data)

# Retrieve cached image
{:ok, data} = ImageCache.get("image_key_300x200")

# Generate cache key
key = ImageCache.generate_key(image_data, processing_options)

Summary

Types

cache_config()
cache_entry()
cache_key()
cache_stats()

Functions

batch(operations)

Performs batch cache operations for improved performance.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

clear()

Clears all entries from the cache.

delete(key)

Removes an entry from the cache.

generate_key(image_data, options \\ %{})

Generates a cache key from image data and processing options.

get(key)

Retrieves a cached image by key.

get_stats()

Gets current cache statistics.

preload(image_specs)

Preloads cache with commonly used images.

put(key, data, metadata \\ %{})

Stores an image in the cache.

start_link(init_opts \\ [])

Types

cache_config()

@type cache_config() :: %{
  optional(:max_memory) => non_neg_integer(),
  optional(:max_entries) => non_neg_integer(),
  optional(:ttl) => non_neg_integer(),
  optional(:enable_disk_cache) => boolean(),
  optional(:disk_cache_dir) => String.t(),
  optional(:cleanup_interval) => non_neg_integer(),
  optional(:metrics_enabled) => boolean()
}

cache_entry()

@type cache_entry() :: %{
  data: binary(),
  metadata: map(),
  accessed_at: integer(),
  created_at: integer(),
  size: non_neg_integer(),
  hit_count: non_neg_integer()
}

cache_key()

@type cache_key() :: String.t()

cache_stats()

@type cache_stats() :: %{
  entries: non_neg_integer(),
  memory_usage: non_neg_integer(),
  hit_rate: float(),
  total_hits: non_neg_integer(),
  total_misses: non_neg_integer(),
  evictions: non_neg_integer()
}

Functions

batch(operations)

@spec batch([tuple()]) :: {:ok, [term()]} | {:error, term()}

Performs batch cache operations for improved performance.

Parameters

  • operations - List of cache operations: {:get, key}, {:put, key, data}, etc.

Returns

  • {:ok, results} - List of operation results
  • {:error, reason} - Batch operation failed

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

clear()

@spec clear() :: :ok

Clears all entries from the cache.

Returns

  • :ok - Cache cleared successfully

delete(key)

@spec delete(cache_key()) :: :ok

Removes an entry from the cache.

Parameters

  • key - Cache key to remove

Returns

  • :ok - Successfully removed or key didn't exist

generate_key(image_data, options \\ %{})

@spec generate_key(binary(), map()) :: cache_key()

Generates a cache key from image data and processing options.

Uses SHA-256 hashing for consistent, collision-resistant keys.

Parameters

  • image_data - Source image data
  • options - Processing options that affect output

Returns

  • Cache key string

get(key)

@spec get(cache_key()) :: {:ok, binary()} | {:error, :not_found | :expired}

Retrieves a cached image by key.

Parameters

  • key - Cache key to lookup

Returns

  • {:ok, data} - Found cached data
  • {:error, :not_found} - Key not in cache
  • {:error, :expired} - Entry has expired

get_stats()

@spec get_stats() :: cache_stats()

Gets current cache statistics.

Returns

  • Cache statistics map with performance metrics

preload(image_specs)

@spec preload([{cache_key(), binary(), map()}]) :: :ok

Preloads cache with commonly used images.

Parameters

  • image_specs - List of {key, image_data, metadata} tuples

Returns

  • :ok - Preloading completed

put(key, data, metadata \\ %{})

@spec put(cache_key(), binary(), map()) :: :ok | {:error, term()}

Stores an image in the cache.

Parameters

  • key - Cache key
  • data - Image data to cache
  • metadata - Optional metadata about the image

Returns

  • :ok - Successfully cached
  • {:error, reason} - Failed to cache

start_link(init_opts \\ [])