Raxol.Terminal.Manager (Raxol v2.0.1)

Terminal manager module.

This module manages terminal sessions, including:

Session creation
Session destruction
Session listing
Session monitoring

Event Handling and Notification System

The manager processes terminal events using pattern matching on the canonical Raxol.Core.Events.Event struct. Each event type (e.g., :window, :mode, :focus, :clipboard, :selection, :paste, :cursor, :scroll) is handled with clear, semantic matches on the expected data fields.

For each event, the manager:

Updates the terminal state as needed
Notifies the runtime process (if present) via message passing
Logs the event using Raxol.Core.Runtime.Log
Emits a Telemetry event for observability
Calls a user-defined callback module (if provided)

Extending Event Handling

To add a new event type:

Add a new clause in the handle_call({:process_event, %Raxol.Core.Events.Event{type: ..., data: ...}}, ...) function.
Add a corresponding notification helper (e.g., notify_new_event/2) if needed.
Ensure the notification helper sends a message, logs, emits telemetry, and calls the callback module if present.

User-defined Callback Modules

You can pass a :callback_module option to start_link/1 to receive notifications for terminal events. The callback module must implement the Raxol.Terminal.Manager.Callback behaviour:

defmodule MyTerminalCallback do
  @behaviour Raxol.Terminal.Manager.Callback

  # ...implement other callbacks as needed
end

{:ok, pid} = Raxol.Terminal.Manager.start_link(callback_module: MyTerminalCallback)

Telemetry Events

Each notification emits a telemetry event under the [:raxol, :terminal, ...] prefix. You can attach handlers for metrics, tracing, or custom logic.

Logging

All notifications are logged at the info level for easy debugging and auditability.

Summary

Types

t()

Functions

batch_update_screen(pid \\ __MODULE__, updates)

Updates the terminal screen with multiple updates in a batch.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

count_sessions(pid \\ __MODULE__)

Gets the count of terminal sessions.

create_session(pid \\ __MODULE__, opts \\ [])

Creates a new terminal session.

destroy_session(pid \\ __MODULE__, session_id)

Destroys a terminal session.

get_session(pid \\ __MODULE__, session_id)

Gets a terminal session by ID.

get_terminal_state(pid \\ __MODULE__)

Gets the current terminal state.

handle_manager_cast(msg, state)

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

list_sessions(pid \\ __MODULE__)

Lists all terminal sessions.

monitor_session(pid \\ __MODULE__, session_id)

Monitors a terminal session.

process_event(pid \\ __MODULE__, event)

Processes a terminal event.

start_link(init_opts \\ [])

start_link_custom(opts \\ [])

Starts the terminal manager.

unmonitor_session(pid \\ __MODULE__, session_id)

Unmonitors a terminal session.

update_screen(pid \\ __MODULE__, update)

Updates the terminal screen.

Types

t()

@type t() :: %Raxol.Terminal.Manager{
  callback_module: module() | nil,
  runtime_pid: pid() | nil,
  sessions: map(),
  terminal: Raxol.Terminal.Emulator.t() | nil
}

Functions

batch_update_screen(pid \\ MODULE, updates)

Updates the terminal screen with multiple updates in a batch.

Examples

iex> {:ok, pid} = Manager.start_link()
iex> updates = [%{type: :clear_screen}, %{type: :set_cursor, x: 0, y: 0}]
iex> :ok = Manager.batch_update_screen(pid, updates)

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

count_sessions(pid \\ MODULE)

Gets the count of terminal sessions.

Examples

iex> {:ok, pid} = Manager.start_link()
iex> {:ok, _} = Manager.create_session(pid)
iex> {:ok, _} = Manager.create_session(pid)
iex> Manager.count_sessions(pid)
2

create_session(pid \\ MODULE, opts \\ [])

Creates a new terminal session.

Examples

iex> {:ok, pid} = Manager.start_link()
iex> {:ok, session_id} = Manager.create_session(pid, %{width: 80, height: 24})
iex> binary?(session_id)
true

destroy_session(pid \\ MODULE, session_id)

Destroys a terminal session.

Examples

iex> {:ok, pid} = Manager.start_link()
iex> {:ok, session_id} = Manager.create_session(pid)
iex> :ok = Manager.destroy_session(pid, session_id)
iex> Manager.get_session(pid, session_id)
{:error, :not_found}

get_session(pid \\ MODULE, session_id)

Gets a terminal session by ID.

Examples

iex> {:ok, pid} = Manager.start_link()
iex> {:ok, session_id} = Manager.create_session(pid)
iex> {:ok, session} = Manager.get_session(pid, session_id)
iex> session.id
session_id

get_terminal_state(pid \\ MODULE)

Gets the current terminal state.

Examples

iex> {:ok, pid} = Manager.start_link(terminal: %{width: 80, height: 24})
iex> state = Manager.get_terminal_state(pid)
iex> state.width
80

handle_manager_cast(msg, state)

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

list_sessions(pid \\ MODULE)

Lists all terminal sessions.

Examples

iex> {:ok, pid} = Manager.start_link()
iex> {:ok, session_id1} = Manager.create_session(pid)
iex> {:ok, session_id2} = Manager.create_session(pid)
iex> sessions = Manager.list_sessions(pid)
iex> length(sessions)
2

monitor_session(pid \\ MODULE, session_id)

Monitors a terminal session.

Examples

iex> {:ok, pid} = Manager.start_link()
iex> {:ok, session_id} = Manager.create_session(pid)
iex> :ok = Manager.monitor_session(pid, session_id)
iex> Process.whereis({:via, Registry, {Registry, session_id}})
#PID<0.123.0>

process_event(pid \\ MODULE, event)

Processes a terminal event.

Examples

iex> {:ok, pid} = Manager.start_link()
iex> event = %Raxol.Core.Events.Event{type: :focus, data: %{focused: true}}
iex> :ok = Manager.process_event(pid, event)

start_link(init_opts \\ [])

start_link_custom(opts \\ [])

Starts the terminal manager.

Options

:terminal - The initial terminal emulator state (required for single-terminal mode)
:runtime_pid - The runtime process PID (optional)
:callback_module - The callback module for the manager (optional)

Examples

iex> {:ok, pid} = Manager.start_link(terminal: term, runtime_pid: self())
iex> Process.alive?(pid)
true

unmonitor_session(pid \\ MODULE, session_id)

Unmonitors a terminal session.

Examples

iex> {:ok, pid} = Manager.start_link()
iex> {:ok, session_id} = Manager.create_session(pid)
iex> :ok = Manager.monitor_session(pid, session_id)
iex> :ok = Manager.unmonitor_session(pid, session_id)
iex> Process.whereis({:via, Registry, {Registry, session_id}})
nil

update_screen(pid \\ MODULE, update)

Updates the terminal screen.

Examples

iex> {:ok, pid} = Manager.start_link()
iex> update = %{type: :clear_screen}
iex> :ok = Manager.update_screen(pid, update)