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

View Source

Advanced memory management system for terminal graphics operations.

This module provides:

  • Intelligent memory allocation and pooling
  • Graphics memory optimization strategies
  • Automatic garbage collection for graphics resources
  • Memory usage monitoring and reporting
  • Prevention of memory leaks in graphics operations
  • Dynamic memory scaling based on workload

Features

Memory Pooling

  • Pre-allocated memory pools for different graphics sizes
  • Pool-specific allocation strategies (FIFO, LRU, Size-based)
  • Dynamic pool resizing based on usage patterns
  • Memory fragmentation prevention

Resource Management

  • Automatic cleanup of unused graphics resources
  • Reference counting for shared graphics elements
  • Weak references to prevent memory leaks
  • Resource lifecycle tracking

Performance Optimization

  • Memory access pattern optimization
  • Cache-friendly memory layouts
  • NUMA-aware allocation on supported systems
  • Memory prefetching for predictable access patterns

Usage

# Initialize memory manager
{:ok, manager} = MemoryManager.start_link(%{
  total_budget: 256_000_000,  # 256MB
  pool_strategy: :adaptive,
  gc_strategy: :generational
})

# Allocate graphics memory
{:ok, buffer} = MemoryManager.allocate(manager, 1024 * 1024, %{
  type: :image_buffer,
  usage: :read_write,
  lifetime: :long
})

# Use memory pools
{:ok, pool} = MemoryManager.create_pool(manager, :image_thumbnails, %{
  chunk_size: 256 * 256 * 4,  # 256x256 RGBA
  initial_count: 50,
  max_count: 200
})

Summary

Functions

Allocates memory for graphics operations.

Allocates memory from a specific pool.

Returns a specification to start this module under a supervisor.

Creates a memory pool for frequently allocated graphics of the same size.

Deallocates previously allocated memory.

Defragments memory pools to reduce fragmentation.

Forces garbage collection of unused graphics resources.

Gets current memory usage statistics.

Returns memory to a specific pool for reuse.

Sets memory budget dynamically.

Types

allocation_id()

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

allocation_info()

@type allocation_info() :: %{
  id: allocation_id(),
  size: non_neg_integer(),
  type: atom(),
  usage: :read_only | :write_only | :read_write,
  lifetime: :short | :medium | :long,
  allocated_at: non_neg_integer(),
  last_accessed: non_neg_integer(),
  reference_count: non_neg_integer()
}

memory_budget()

@type memory_budget() :: non_neg_integer()

memory_pool()

@type memory_pool() :: %{
  id: pool_id(),
  chunk_size: non_neg_integer(),
  chunk_count: non_neg_integer(),
  max_chunks: non_neg_integer(),
  available_chunks: [term()],
  allocated_chunks: [term()],
  allocation_strategy: :fifo | :lifo | :lru | :adaptive,
  created_at: non_neg_integer()
}

memory_stats()

@type memory_stats() :: %{
  total_budget: memory_budget(),
  allocated: non_neg_integer(),
  available: non_neg_integer(),
  peak_usage: non_neg_integer(),
  allocation_count: non_neg_integer(),
  pool_stats: map(),
  fragmentation_ratio: float()
}

pool_id()

@type pool_id() :: atom()

Functions

allocate(size, metadata \\ %{})

@spec allocate(non_neg_integer(), map()) ::
  {:ok, {allocation_id(), term()}} | {:error, term()}

Allocates memory for graphics operations.

Parameters

  • size - Size in bytes to allocate
  • metadata - Allocation metadata (type, usage, lifetime)

Returns

  • {:ok, {allocation_id, buffer}} - Successfully allocated
  • {:error, reason} - Allocation failed

Examples

{:ok, {id, buffer}} = MemoryManager.allocate(1024 * 1024, %{
  type: :image_buffer,
  usage: :read_write,
  lifetime: :medium
})

allocate_from_pool(pool_id, metadata \\ %{})

@spec allocate_from_pool(pool_id(), map()) ::
  {:ok, {allocation_id(), term()}} | {:error, term()}

Allocates memory from a specific pool.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

create_pool(pool_id, config)

@spec create_pool(pool_id(), map()) :: {:ok, memory_pool()} | {:error, term()}

Creates a memory pool for frequently allocated graphics of the same size.

Parameters

  • pool_id - Unique identifier for the pool
  • config - Pool configuration (chunk_size, initial_count, etc.)

Examples

{:ok, pool} = MemoryManager.create_pool(:thumbnails, %{
  chunk_size: 256 * 256 * 4,  # 256x256 RGBA
  initial_count: 20,
  max_count: 100,
  strategy: :lru
})

deallocate(allocation_id)

@spec deallocate(allocation_id()) :: :ok | {:error, term()}

Deallocates previously allocated memory.

defragment()

@spec defragment() :: {:ok, memory_stats()} | {:error, term()}

Defragments memory pools to reduce fragmentation.

garbage_collect()

@spec garbage_collect() :: {:ok, memory_stats()} | {:error, term()}

Forces garbage collection of unused graphics resources.

get_stats()

@spec get_stats() :: memory_stats()

Gets current memory usage statistics.

handle_manager_cast(msg, state)

Callback implementation for Raxol.Core.Behaviours.BaseManager.handle_manager_cast/2.

return_to_pool(pool_id, allocation_id)

@spec return_to_pool(pool_id(), allocation_id()) :: :ok | {:error, term()}

Returns memory to a specific pool for reuse.

set_budget(new_budget)

@spec set_budget(memory_budget()) :: :ok | {:error, term()}

Sets memory budget dynamically.

start_link(init_opts \\ [])