Dynamic supervisor for managing individual session processes.
This supervisor is responsible for the lifecycle management of all session processes. It handles starting, stopping, and monitoring session processes dynamically as they are created and destroyed during application runtime.
Key Responsibilities
Process Management
- Dynamically starts session processes on demand
- Terminates session processes when requested or when they expire
- Tracks all active session processes
- Provides process lookup by session ID
Registry Integration
- Registers each session process in
Phoenix.SessionProcess.Registry - Ensures unique session ID to process mappings
- Enables fast process lookup for communication
Telemetry Integration
- Emits telemetry events for all operations
- Tracks session lifecycle metrics
- Monitors performance and error rates
Public API
This module provides the main internal API for session process management:
Session Lifecycle
start_session/1-2- Start new session processesterminate_session/1- Terminate specific sessionsession_process_started?/1- Check if session existssession_process_pid/1- Get process PID for session ID
Process Communication
call_session/4- GenServer call to session processcast_session/3- GenServer cast to session process
Administrative Functions
start_child/2- Generic child process starterterminate_child/1- Generic child process terminatorcount_children/0- Get count of active sessions
Process Strategy
Uses :one_for_one strategy which means:
- If a session process crashes, only that process is restarted
- Other session processes continue unaffected
- Provides isolation between user sessions
Error Handling
All operations include comprehensive error handling:
- Invalid session IDs are rejected
- Session limits are enforced
- Process failures are logged and monitored
- Telemetry events are emitted for debugging
Performance Considerations
- Registry provides O(1) session lookups
- Dynamic supervisor scales to thousands of sessions
- Each session process is isolated and lightweight
- Memory usage scales linearly with session count
Example Usage
This module is typically used internally by the main Phoenix.SessionProcess API,
but can also be used directly for advanced scenarios:
# Start a session process
{:ok, pid} = ProcessSupervisor.start_session("user_123")
# Check if session exists
started? = ProcessSupervisor.session_process_started?("user_123")
# Terminate a session
:ok = ProcessSupervisor.terminate_session("user_123")Summary
Functions
Returns a specification to start this module under a supervisor.
Initializes the dynamic supervisor.
Checks if a session process has been started for the given session ID.
Starts a child process using the dynamic supervisor.
Starts the process supervisor.
Starts a session process using the default configured module.
Starts a session process with options.
Terminates a child process.
Terminates a session process for the given session ID.
Functions
Returns a specification to start this module under a supervisor.
See Supervisor.
Initializes the dynamic supervisor.
Parameters
_init_arg- Initialization arguments (unused)
Returns
{:ok, supervisor_config}- Supervisor initialized successfully
Checks if a session process has been started for the given session ID.
Parameters
session_id- The session ID to check
Returns
boolean()-trueif the session process exists,falseotherwise
Starts a child process using the dynamic supervisor.
This is a generic function that can start any child process under this supervisor. It's primarily used internally for starting session processes.
Parameters
worker- The module to start as a child processworker_arg- Arguments to pass to the child process
Returns
{:ok, pid()}- Child process started successfully{:error, reason}- Failed to start child process
Starts the process supervisor.
This function is typically called by the top-level supervisor when starting the Phoenix.SessionProcess system.
Parameters
init_arg- Initialization arguments (unused, kept for compatibility)
Returns
{:ok, pid()}- Supervisor started successfully{:error, reason}- Failed to start supervisor:ignore- Supervisor should be ignored
Starts a session process using the default configured module.
Parameters
session_id- Unique identifier for the session
Returns
{:ok, pid()}- Session process started successfully{:error, reason}- Failed to start session process
Starts a session process with options.
Parameters
session_id- Unique identifier for the sessionopts- Keyword list of options::module- Session process module to use (defaults to configured module):args- Initialization arguments passed toinit/1(defaults to nil)
Returns
{:ok, pid()}- Session process started successfully{:error, reason}- Failed to start session process
Examples
# Use default module with no args
start_session("session_123")
# Use custom module with default args
start_session("session_123", module: MyApp.SessionProcess)
# Use custom module with custom args
start_session("session_123", module: MyApp.SessionProcess, args: %{user_id: 123})
# Use default module with custom args
start_session("session_123", args: %{user_id: 123})Terminates a child process.
Parameters
pid- The PID of the child process to terminate
Returns
:ok- Child process terminated successfully{:error, reason}- Failed to terminate child process
@spec terminate_session(binary()) :: :ok | {:error, :not_found}
Terminates a session process for the given session ID.
This function gracefully shuts down the session process and emits telemetry events for monitoring and debugging purposes.
Parameters
session_id- The session ID whose process should be terminated
Returns
:ok- Session process terminated successfully{:error, :not_found}- Session process not found
Side Effects
- Emits telemetry event for session termination
- Removes process from registry
- Cancels scheduled cleanup and removes activity tracking
- Logs the termination operation