GenServer managing double-buffered screen rendering.

The BufferManager owns two ETS-based buffers:

• Current buffer: Components write to this buffer
• Previous buffer: Contains the last rendered frame for diffing

After rendering, swap_buffers/0 exchanges the buffer references atomically. This enables efficient differential updates without copying buffer contents.

Usage

# Start the manager
{:ok, pid} = BufferManager.start_link(rows: 24, cols: 80)

# Get buffer for writing
buffer = BufferManager.get_current_buffer()
Buffer.set_cell(buffer, 1, 1, Cell.new("X"))

# Mark dirty after modifications
BufferManager.mark_dirty()

# Check if render needed
if BufferManager.dirty?() do
  current = BufferManager.get_current_buffer()
  previous = BufferManager.get_previous_buffer()
  # ... perform diff and render ...
  BufferManager.swap_buffers()
  BufferManager.clear_dirty()
end

Concurrency

Multiple processes can write to the current buffer concurrently via ETS. Cell writes are atomic but unordered—last writer wins for overlapping cells. Components should write to non-overlapping regions for deterministic results.

Important: This module is designed for a single-writer pattern where one process (typically the render loop) coordinates buffer access. If you hold a buffer reference while another process calls swap_buffers/1, your writes will go to the wrong buffer. To avoid this race condition:

1. Complete all writes before calling swap_buffers/1
2. Use a single coordinator process for the write → swap cycle
3. Don't cache buffer references across swap operations

Typical Render Loop

# Single process coordinates all buffer access
buffer = BufferManager.get_current_buffer()

# All writes happen here
Buffer.write_string(buffer, 1, 1, "Hello")
BufferManager.mark_dirty()

# Only swap after writes are complete
if BufferManager.dirty?() do
  current = BufferManager.get_current_buffer()
  previous = BufferManager.get_previous_buffer()
  operations = Diff.diff(current, previous)
  # ... render operations ...
  BufferManager.swap_buffers()
  BufferManager.clear_dirty()
end

Direct Access

Most operations bypass the GenServer for maximum throughput. Buffer references and the dirty flag are stored in :persistent_term for lock-free access from any process. Only swap_buffers/1 and resize/3 require GenServer coordination.

Dirty Flag

The dirty flag uses :atomics for lock-free concurrent access. Any process can mark the buffer dirty after modifications, and the renderer checks and clears the flag during the render cycle.