Phoenix.SocketClient.HibernationManager (phoenix_socket_client v0.8.0)

View Source

Process hibernation manager for idle connections.

This module provides intelligent hibernation for long-lived processes to reduce memory footprint when connections are idle. It monitors process activity and automatically hibernates processes that have been idle for a configurable period.

Features

  • Automatic detection of idle processes
  • Configurable hibernation thresholds
  • Memory-efficient hibernation strategy
  • Activity monitoring and wake-up handling
  • Process lifecycle management

Usage

The hibernation manager is automatically started by the socket supervisor and monitors all socket-related processes for inactivity.

Performance Benefits

  • Reduces memory usage for idle connections
  • Lowers GC pressure from idle processes
  • Maintains responsiveness while optimizing memory
  • Provides configurable hibernation policies

Summary

Types

opts()

Hibernation manager configuration options

process_info()

Tracked process information

t()

Hibernation manager state

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

hibernate_process(manager_pid, pid)

Forces hibernation of a specific process.

register_process(manager_pid, pid, name \\ nil)

Registers a process for hibernation monitoring.

report_activity(manager_pid, pid)

Reports activity for a process.

start_link(opts \\ [])

Starts the hibernation manager.

stats(manager_pid)

Gets hibernation statistics for monitoring.

unregister_process(manager_pid, pid)

Unregisters a process from hibernation monitoring.

wake_up_process(manager_pid, pid)

Manually wakes up a hibernated process.

Types

opts()

@type opts() :: [
  idle_timeout: non_neg_integer(),
  check_interval: non_neg_integer(),
  memory_threshold: non_neg_integer(),
  registry_name: atom()
]

Hibernation manager configuration options

process_info()

@type process_info() :: %{
  pid: pid(),
  last_activity: integer(),
  memory: non_neg_integer(),
  hibernated_count: non_neg_integer(),
  name: atom() | {atom(), atom()}
}

Tracked process information

t()

@type t() :: %Phoenix.SocketClient.HibernationManager{
  check_interval: non_neg_integer(),
  check_timer: reference() | nil,
  idle_timeout: non_neg_integer(),
  memory_threshold: non_neg_integer(),
  registry_name: atom() | nil,
  stats: %{
    total_hibernations: non_neg_integer(),
    total_memory_saved: non_neg_integer(),
    current_tracked: non_neg_integer(),
    current_hibernated: non_neg_integer()
  },
  tracked_processes: %{required(pid()) => process_info()}
}

Hibernation manager state

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

hibernate_process(manager_pid, pid)

@spec hibernate_process(pid(), pid()) :: :ok | {:error, term()}

Forces hibernation of a specific process.

Useful for manual hibernation during maintenance or testing.

register_process(manager_pid, pid, name \\ nil)

@spec register_process(pid(), pid(), atom() | {atom(), atom()}) :: :ok

Registers a process for hibernation monitoring.

The process will be tracked for activity and hibernated when idle.

report_activity(manager_pid, pid)

@spec report_activity(pid(), pid()) :: :ok

Reports activity for a process.

This should be called when a process receives a message or performs work to update its activity timestamp and prevent premature hibernation.

start_link(opts \\ [])

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

Starts the hibernation manager.

Options

  • :idle_timeout - Time in milliseconds before considering a process idle (default: 300000)
  • :check_interval - Interval for checking idle processes (default: 60000)
  • :memory_threshold - Minimum memory usage before hibernation (default: 10000)
  • :registry_name - Registry name for process discovery

stats(manager_pid)

@spec stats(pid()) :: map()

Gets hibernation statistics for monitoring.

Returns statistics about hibernation effectiveness and current state.

unregister_process(manager_pid, pid)

@spec unregister_process(pid(), pid()) :: :ok

Unregisters a process from hibernation monitoring.

The process will no longer be tracked for hibernation.

wake_up_process(manager_pid, pid)

@spec wake_up_process(pid(), pid()) :: :ok | {:error, term()}

Manually wakes up a hibernated process.

This is typically handled automatically when messages are received.