Entropy.State.ZombieRegistry (Entropy v0.1.0)

View Source

The authoritative record of suspended processes.

This module maintains the "Conservation of Zombies" invariant: every process suspended by Entropy must be tracked until it is resumed or terminated.

Architecture: Intrinsic Safety (Dead Man's Switch)

To prevent "Orphaned Zombies" (processes left permanently suspended because the tool crashed), this registry relies on the fundamental physics of the BEAM VM regarding Resource Ownership.

  1. The Lock: When this Registry calls :erlang.suspend_process/1, the VM increments a suspend count on the victim, tied specifically to the Identity of this Registry process.
  2. The Crash: If this Registry process crashes or terminates for any reason, the VM automatically detects the death of the lock-holder.
  3. The Release: The VM iterates all suspend locks held by the dead process and decrements them. This automatically resumes all zombies without external intervention.

This guarantees that if the Registry dies, the Zombies wake up. The ETS table is tied to the Registry's lifecycle; when the Registry dies, the table is deleted, ensuring the internal state (Table) matches the external reality (No suspended processes).

Responsibilities

  • Suspension: Calls :erlang.suspend_process/1 and schedules a resume timer.
  • Monitoring: Monitors victims. If a victim dies while suspended (e.g., killed by an external supervisor), the record is cleaned up.
  • Resumption: Calls :erlang.resume_process/1 when the TTL expires.

Summary

Functions

Returns a specification to start this module under a supervisor.

Returns the count of currently registered zombies for verification.

Checks if a PID is currently tracked by the registry (active or reserved). Performs an O(1) ETS lookup. Safe to use in high-throughput loops.

Suspends the process and schedules its resumption after ttl_ms.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

count()

Returns the count of currently registered zombies for verification.

is_suspended?(pid)

@spec is_suspended?(pid()) :: boolean()

Checks if a PID is currently tracked by the registry (active or reserved). Performs an O(1) ETS lookup. Safe to use in high-throughput loops.

reserve(victim_pid)

start_link(opts)

suspend(victim_pid, ttl_ms)

Suspends the process and schedules its resumption after ttl_ms.