TermUI.Component.StatePersistence (TermUI v0.2.0)

View Source

ETS-based state persistence for crash recovery.

This module allows components to persist their state before crashes and recover it on restart. State is stored in an ETS table that survives component process crashes.

Usage

# Persist state (typically called on state changes)
StatePersistence.persist(:my_component, state)

# Recover state on restart
case StatePersistence.recover(:my_component) do
  {:ok, state} -> {:ok, state}
  :not_found -> {:ok, initial_state}
end

# Clear persisted state
StatePersistence.clear(:my_component)

Summary

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

clear(component_id)

Clears persisted state for a component.

clear_all()

Clears all persisted state.

clear_restart_history(component_id)

Clears restart history for a component.

count()

Returns the count of persisted states.

get_metadata(component_id)

Gets metadata about persisted state.

get_restart_count(component_id)

Gets the restart count for a component within the time window.

list_persisted()

Lists all component IDs with persisted state.

persist(component_id, state, opts \\ [])

Persists component state to ETS.

record_restart(component_id)

Records restart event for a component.

recover(component_id, mode \\ :last_state)

Recovers persisted state for a component.

restart_limit_reached?(component_id)

Checks if restart intensity limit has been reached.

set_restart_limits(component_id, max_restarts, max_seconds)

Sets restart intensity limits for a component.

start_link(opts \\ [])

Starts the state persistence server.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

clear(component_id)

@spec clear(term()) :: :ok

Clears persisted state for a component.

Parameters

  • component_id - Component identifier

Returns

  • :ok - State cleared (or was not present)

clear_all()

@spec clear_all() :: :ok

Clears all persisted state.

Mainly useful for testing.

clear_restart_history(component_id)

@spec clear_restart_history(term()) :: :ok

Clears restart history for a component.

count()

@spec count() :: non_neg_integer()

Returns the count of persisted states.

get_metadata(component_id)

@spec get_metadata(term()) :: {:ok, map()} | :not_found

Gets metadata about persisted state.

Returns

  • {:ok, metadata} - Metadata including persisted_at timestamp
  • :not_found - No state persisted for this component

get_restart_count(component_id)

@spec get_restart_count(term()) :: non_neg_integer()

Gets the restart count for a component within the time window.

list_persisted()

@spec list_persisted() :: [term()]

Lists all component IDs with persisted state.

persist(component_id, state, opts \\ [])

@spec persist(term(), term(), keyword()) :: :ok

Persists component state to ETS.

Parameters

  • component_id - Component identifier
  • state - State to persist
  • opts - Options
    • :props - Original props for last_props recovery mode

Returns

  • :ok - State persisted successfully

record_restart(component_id)

@spec record_restart(term()) :: :ok

Records restart event for a component.

Used for tracking restart counts and detecting restart storms.

recover(component_id, mode \\ :last_state)

@spec recover(term(), atom()) :: {:ok, term()} | :not_found

Recovers persisted state for a component.

Parameters

  • component_id - Component identifier
  • mode - Recovery mode (default: :last_state)
    • :last_state - Return the full persisted state
    • :last_props - Return only the persisted props
    • :reset - Return :not_found (forces re-initialization)

Returns

  • {:ok, state} - State found and returned
  • :not_found - No state persisted for this component

restart_limit_reached?(component_id)

@spec restart_limit_reached?(term()) :: boolean()

Checks if restart intensity limit has been reached.

Returns

  • true - Restart limit exceeded
  • false - Within limits

set_restart_limits(component_id, max_restarts, max_seconds)

@spec set_restart_limits(term(), non_neg_integer(), non_neg_integer()) :: :ok

Sets restart intensity limits for a component.

Parameters

  • component_id - Component identifier
  • max_restarts - Maximum restarts allowed
  • max_seconds - Time window in seconds

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts the state persistence server.