Module

server.pid_manager

PID file management for Bengal dev server.

Tracks running server processes and provides recovery from stale processes.

Features:

  • Automatic stale process detection
  • Graceful process termination (SIGTERM then SIGKILL)
  • PID file validation (ensures it's actually a Bengal process)
  • Cross-platform support (psutil optional, falls back to os.kill)

Usage:

# Check for stale processes
pid_file = PIDManager.get_pid_file(project_root)
stale_pid = PIDManager.check_stale_pid(pid_file)

if stale_pid:
    PIDManager.kill_stale_process(stale_pid)

# Write current PID
PIDManager.write_pid_file(pid_file)

# Check port usage
port_pid = PIDManager.get_process_on_port(5173)
if port_pid:
    print(f"Port in use by PID {port_pid}")

The PID file (.bengal/server.pid) is created in the .bengal directory and automatically cleaned up on normal server shutdown. If the server crashes or is killed, the PID file remains and is detected on next startup.

View source
1 Class

Classes

PIDManager
Manage PID files for process tracking and recovery. Features: - Detect stale processes - Graceful …
6

Manage PID files for process tracking and recovery.

Features:

  • Detect stale processes
  • Graceful process termination
  • PID file validation
  • Cross-platform support

Methods 6

get_pid_file staticmethod
Get the PID file path for a project.
1 Path 
def get_pid_file(project_root: Path) -> Path

Get the PID file path for a project.

Parameters 1
project_root Path

Root directory of Bengal project
Returns

Path —

Path to PID file in .bengal/ directory

is_bengal_process staticmethod
Check if PID is actually a Bengal serve process. Uses psutil if available for …
1 bool 
def is_bengal_process(pid: int) -> bool

Check if PID is actually a Bengal serve process.

Uses psutil if available for accurate process name checking. Falls back to simple existence check if psutil is not installed.

Parameters 1
pid int

Process ID to check
Returns

bool —

True if process is Bengal serve, False otherwise

check_stale_pid staticmethod
Check for stale PID file and return PID if found. A stale PID file indicates a…
1 int | None 
def check_stale_pid(pid_file: Path) -> int | None

Check for stale PID file and return PID if found.

A stale PID file indicates a previous server instance that didn't shut down cleanly (crash, kill -9, power loss, etc.).

This method:

  1. Reads the PID file
  2. Checks if the process exists
  3. Verifies it's actually a Bengal process
  4. Returns the PID if stale, None otherwise

Invalid or empty PID files are automatically cleaned up.

Parameters 1
pid_file Path

Path to PID file
Returns

int | None —

PID of stale process, or None if no stale process

kill_stale_process staticmethod
Gracefully kill a stale process. Tries SIGTERM first (graceful), then SIGKILL …
2 bool 
def kill_stale_process(pid: int, timeout: float = 5.0) -> bool

Gracefully kill a stale process.

Tries SIGTERM first (graceful), then SIGKILL if needed.

Parameters 2
pid int

Process ID to kill
timeout float

Seconds to wait for graceful shutdown
Returns

bool —

True if process was killed, False otherwise

write_pid_file staticmethod
Write current process PID to file. Uses atomic write to ensure the PID file is…
1 None 
def write_pid_file(pid_file: Path) -> None

Write current process PID to file.

Uses atomic write to ensure the PID file is crash-safe.

Parameters 1
pid_file Path

Path to PID file
get_process_on_port staticmethod
Get the PID of process listening on a port. Uses lsof to find which process is…
1 int | None 
def get_process_on_port(port: int) -> int | None

Get the PID of process listening on a port.

Uses lsof to find which process is listening on a port. This is useful for detecting port conflicts.

Parameters 1
port int

Port number to check
Returns

int | None —

PID if found, None otherwise