Raxol.Terminal.Manager (Raxol v0.5.0)
View SourceTerminal 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
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
@type t() :: %Raxol.Terminal.Manager{ callback_module: module() | nil, runtime_pid: pid() | nil, sessions: map(), terminal: Raxol.Terminal.Emulator.t() | nil }
Functions
Returns a specification to start this module under a supervisor.
See Supervisor
.
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
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
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}
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
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
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>
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
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