httk.core.memguard¶
Run a command inside a Linux memory-guarded process group.
The child command starts in its own session (and therefore its own process
group), every process it forks inherits an optional per-process virtual
address-space rlimit, and a watchdog sums the resident memory of the whole
group at a fixed interval using proportional set size (PSS), so shared pages
are divided among the processes mapping them. When total PSS exceeds the budget the
entire group receives SIGKILL — sacrificing the run, never the machine.
This is the userland fallback for environments without a delegatable cgroup v2
subtree (where memory.max on a dedicated cgroup would do the same job in
the kernel). It guards against the failure mode that motivated it: a parallel
test or benchmark run whose workers independently grow until the system-wide
OOM killer takes down unrelated processes.
The process-group sampler requires Linux and readable /proc/PID/smaps_rollup
files. If accounting is unavailable, the command exits with a clear error
instead of running without its memory guard.
Usage:
python -m httk.core.memguard [--max-pss-gb N] [--as-gb N] [--interval SECONDS] -- command args...
--max-rss-gb remains an alias for the PSS budget for existing callers.
The exit status is the child’s status, or 137 when the watchdog killed the group.
Functions¶
Module Contents¶
- httk.core.memguard.main(argv=None, *, prog='httk memguard')¶
Run the requested command under the process-group memory guard.
- Parameters:
argv (collections.abc.Sequence[str] | None) – Command-line arguments, excluding the program name. When omitted, arguments are read from
sys.argv.prog (str) – Program name displayed in command-line help.
- Returns:
The child exit status, 137 for a budget breach, or 2 when the platform cannot provide the Linux process-group PSS sampler.
- Return type:
- httk.core.memguard.command(argv, context)¶
Adapt the memory guard to the top-level
httkcommand contract.