Raxol.Terminal.Manager (Raxol v0.5.0)

View Source

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:

  1. Add a new clause in the handle_call({:process_event, %Raxol.Core.Events.Event{type: ..., data: ...}}, ...) function.
  2. Add a corresponding notification helper (e.g., notify_new_event/2) if needed.
  3. 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

  def focus_changed(focused, _state), do: IO.inspect({:focus, focused})
  def resized(w, h, _state), do: IO.inspect({:resize, w, h})
  # ...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

Functions

Returns a specification to start this module under a supervisor.

Gets the count of terminal sessions.

Creates a new terminal session.

Destroys a terminal session.

Gets a terminal session by ID.

Lists all terminal sessions.

Monitors a terminal session.

Starts the terminal manager.

Unmonitors a terminal session.

Types

t()

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

Functions

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> is_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

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>

start_link(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