SysProc

SysProc class.

Wrapper of psutil.Process class. This class that only exposes necessary functionalities to easily manage shell processes.

Functions

__init__

Initialize self. See help(type(self)) for accurate signature.

process : psutil.Process | None

use_process_group : bool - False

get_all_children

Return all the chlidren of process recursively.

Return type : list

get_process

Return type : Process

is_alive

Return type : bool

is_zombie

Return type : bool

kill

kill_with_children

Kill the process and all its children.

If the process was started with a process group (start_new_session=True), sends SIGTERM to the entire process group first for graceful shutdown, waits briefly, then sends SIGKILL to any survivors. Otherwise, falls back to killing each child individually.

stats

Get process statistics

Return type : dict

wait

Wait for a process PID to terminate

timeout : Any

popen @classmethod

cmd : Any

Return type : SysProc

find_marked_processes @staticmethod

Find all processes carrying marker_env_var in their environment.

The app layer sets marker_env_var on every app child (and thus its whole inherited tree), so this locates app processes regardless of which port they ended up on.

marker_env_var : str

env var name that identifies an app process (e.g. GWS_APP_ID)

Return type : tuple

from_pid @staticmethod

pid : Any

Return type : SysProc

kill_orphan_app_processes @staticmethod

Kill app child processes left over from a previous, uncleanly-stopped server run.

Apps are spawned in their own process group (start_new_session=True), so a hard server stop (SIGKILL, crash, OOM, closing the terminal) leaves them running with no one tracking them. On the next boot they must be reaped explicitly, before any port allocation, or their RAM accumulates run after run (see issue #97).

Detection is by the marker_env_var environment variable. This catches orphans regardless of which port they ended up on. When reading process environments is denied (AccessDenied), falls back to a port-band sweep so the reaper still works under stricter permissions.

This kills EVERY marked process, so it is only safe at boot, when no app is tracked yet. For mid-session use, find the marked processes and kill only the untracked ones.

marker_env_var : str

env var name that identifies an app process (e.g. GWS_APP_ID)

port_band : range

the range of local ports apps may bind to, used for the fallback sweep

Return type : list

kill_process_on_port @staticmethod

Find any process with a LISTEN socket on port and kill its entire process group.

Killing the process group (SIGKILL via killpg) takes down the listener plus its supervisor and siblings atomically — necessary for runners like Reflex where the listener's parent would otherwise respawn a replacement between our kill and the next bind attempt.

Returns the list of PIDs that were targeted (may be empty). If the OS denies access to enumerate sockets, logs a warning and returns [].

port : int

Return type : list

killpg_of_pids @staticmethod

SIGKILL the process groups of the given pids, deduplicating groups.

pids : list

the pids whose process groups to kill

reason : str

prefix for the per-process warning log line, for context

Return type : list

Have you developed a brick?