Raxol.Core.Runtime.Lifecycle (Raxol v2.6.1)

View Source

Manages the application lifecycle, including startup, shutdown, and terminal interaction.

Orchestrates initialization of subsystems in order:

  1. PluginManager -- loads and starts plugins
  2. Dispatcher -- manages app model and event routing (TEA update/2 loop)
  3. Terminal Driver -- raw terminal I/O (skipped for :liveview/:ssh environments)
  4. Rendering Engine -- view -> layout -> buffer -> output pipeline

Uses a two-phase readiness pattern: rendering begins only after both dispatcher_ready and plugin_manager_ready flags are set. In dev mode, a CodeReloader is started to watch for source changes and trigger re-renders.

Shutdown & exit trapping

Every child (dispatcher, driver, rendering engine, plugin manager) is start_link'd from init/1, so all are LINKED to this process, and this process traps exits. terminate/2 is the single source of truth for shutdown ordering: it stops children driver-FIRST so the Terminal Driver's own terminate/2 (mode reset, scroll-region reset, stty restore) runs to completion before anything under it is torn down. This runs identically for every stop trigger: our own :shutdown cast, an external abnormal exit signal, or a genuine child crash.

Trapping exits preserves the prior die-together + supervisor-restart contract (an abnormal child/peer exit still stops this process with the same reason, propagated verbatim), while a :normal peer exit is ignored exactly as an untrapped process would have dropped it. One behavioral addition: a genuine child CRASH now incurs the full driver-first teardown BEFORE the crash reason propagates upward (bounded latency: GenServer.stop over the surviving children) -- teardown-on-crash is intentional, not a correctness break.

Sub-modules

  • Lifecycle.Initializer -- component startup sequence
  • Lifecycle.Shutdown -- stop_process, cleanup, registry management

Summary

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

get_app_name(app_module)

Gets the application name for a given module.

handle_cleanup(context)
handle_error(error, context)
initialize_environment(options)

Initializes the runtime environment. (Stub for test compatibility)

lookup_app(app_id)

Looks up a registered app by ID.

start_application(app, opts)

Starts a Raxol application (compatibility wrapper).

start_link(app_module, options \\ [])

Starts and links a new Raxol application lifecycle manager.

stop(pid_or_name)

Stops the Raxol application lifecycle manager.

stop_application(val)

Stops a Raxol application (compatibility wrapper).

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

get_app_name(app_module)

@spec get_app_name(atom()) :: String.t()

Gets the application name for a given module.

handle_cleanup(context)

@spec handle_cleanup(map()) :: :ok | {:error, :cleanup_failed}

handle_error(error, context)

@spec handle_error(term(), term()) ::
  {:stop, :normal, %{}}
  | {:ok, :continue | :reinitialize_resources | :restart_components}

initialize_environment(options)

@spec initialize_environment(keyword()) :: keyword()

Initializes the runtime environment. (Stub for test compatibility)

lookup_app(app_id)

@spec lookup_app(term()) :: {:ok, term()} | {:error, :not_found | :app_not_found}

Looks up a registered app by ID.

start_application(app, opts)

@spec start_application(
  module(),
  keyword()
) :: GenServer.on_start()

Starts a Raxol application (compatibility wrapper).

start_link(app_module, options \\ [])

Starts and links a new Raxol application lifecycle manager.

Options

  • :app_module - Required application module atom.
  • :name - Optional name for registering the GenServer.
  • :width - Terminal width (default: 80).
  • :height - Terminal height (default: 24).
  • :debug - Enable debug mode (default: false).
  • :initial_commands - A list of directive structs to execute on startup.
  • :plugin_manager_opts - Options to pass to the PluginManager's start_link function.
  • :adaptive - Enable adaptive UI (layout recommendations from behavior tracking). Default: false.
  • :alternate_screen - Enter the alternate screen buffer on startup (DECSET 1049). Prevents TUI frames from polluting the client's scrollback. Default: false.

stop(pid_or_name)

Stops the Raxol application lifecycle manager.

stop_application(val)

@spec stop_application(GenServer.server()) :: :ok

Stops a Raxol application (compatibility wrapper).