Peeper.State (peeper v0.3.1)

View Source

Core state management module for the Peeper framework.

This module is responsible for preserving and restoring state between crashes of the wrapped GenServer. It acts as a private state keeper within the Peeper supervision tree, storing the latest state of the GenServer implementation.

Role in Supervision Tree

Peeper.State is a child process in the Peeper supervision tree, started directly under the main Peeper.Supervisor. It maintains:

  1. The current state of the wrapped GenServer
  2. Any ETS tables created by the process that need to be preserved
  3. The process dictionary content that needs to be restored after crashes

Internal Functionality

When the worker GenServer crashes and is restarted by the supervisor, it retrieves its last known state from this state keeper process. This allows the GenServer to maintain state continuity despite crashes, implementing the "Let It Crash" philosophy without losing valuable state.

This module also handles:

  • ETS table ownership transfers between the worker and state processes
  • Process migration between supervisors (including remote nodes)
  • Storage of process dictionary data

This is an internal module that shouldn't be used directly by client code. Instead, interact with Peeper through the public API in the Peeper module.

Summary

Types

Represents a serialized ETS table dump consisting of

Functions

Returns a specification to start this module under a supervisor.

Initializes the State GenServer with the provided state information.

Starts a State GenServer process linked to the current process.

Types

ets_dump()

@type ets_dump() :: {Peeper.name(), [Peeper.ets_option()], [tuple()]}

Represents a serialized ETS table dump consisting of:

  • The table name or identifier
  • A list of table options (access, heir, etc.)
  • The actual table data as a list of tuples

This format allows ETS tables to be recreated with identical configuration and data after a worker process crash.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

init(state)

Initializes the State GenServer with the provided state information.

This function:

  1. Extracts the supervisor PID and any initial state data
  2. Sets up the internal ETS table to store state, dictionary, and ETS tables data
  3. Processes any inherited ETS tables that need special handling

The internal ETS table structure contains three key-value pairs:

  • {:state, state} - The actual application state to be preserved
  • {:dictionary, dictionary} - Process dictionary entries to be restored
  • {:ets, ets} - ETS tables information for recreation after a crash

start_link(state)

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

Starts a State GenServer process linked to the current process.

This function is called by the Peeper.Supervisor to initialize the state keeper that will preserve state between worker restarts.

Parameters

  • state: A keyword list containing initialization parameters with the following keys:
    • :supervisor: PID of the parent supervisor (required)
    • :state: The initial state to be stored (optional)
    • :ets: ETS tables to be preserved (optional)
    • :dictionary: Process dictionary content to preserve (optional)