Skip to main content

Module tree_memory

Module tree_memory 

Source
Expand description

Whole-tree memory cap for a kernel: the kernel plus every process its cells spawn (tree-memory.ts).

  • Cgroup: the kernel starts inside a transient systemd user scope (systemd-run --user --scope -p MemoryMax=… -p MemorySwapMax=0), so the kernel’s memory controller enforces the cap; the host reads the scope’s memory.events to report an OOM kill clearly. Needs no root, only a user manager with the memory controller delegated (probed once per launcher program by starting a tiny scope and reading back its memory.max).
  • Watchdog: the host sums the proportional anonymous and shared memory of the kernel’s descendant tree from /proc (Pss_Anon + Pss_Shmem + SwapPss; RssAnon + RssShmem + VmSwap where PSS is unavailable) and kills the tree when it is over the cap, polling every 500 ms, 250 ms above 40% of the cap and 100 ms above 70%.
  • Off: no tree cap (the cap is 0, or not Linux).

RLIMIT_DATA per process stays in force in every mode.

Enums§

TreeMemoryBackend

Functions§

cgroup_dir_of
The cgroup v2 directory named by a /proc/<pid>/cgroup text.
cgroup_oom_kills
cgroupOomKills: OOM kills recorded in a cgroup’s memory.events (0 without the line), or none when the cgroup is gone.
cgroup_pids
cgroupPids: pids listed in a cgroup’s cgroup.procs and its child cgroups, or none when it is gone.
cgroup_scope_available
cgroupScopeAvailable: whether program (systemd-run) can start a transient user scope with a memory cap here. Probed once per program by starting a tiny scope and reading back its memory.max, which checks the launcher, the user manager and memory-controller delegation together.
cgroup_scope_command
cgroupScopeCommand: the command prefix that starts the kernel inside a capped transient scope; the first item is the launcher (systemd-run), which execs the command after -- itself.
is_foreign_scope
Whether dir may be treated as the kernel’s own scope: it is not this host process’s cgroup nor one of its ancestors. A kernel that was never moved into a scope of its own (a launcher that only execs, or the moment before systemd-run moves it) still sits in the host’s cgroup, and killing “every process in it” would kill the host and the terminal it runs in (on 2026-10-15 a test under a fake systemd-run killed the user’s Ghostty surface this way).
kernel_tree_memory_limit
kernelTreeMemoryLimit: the override, else ULTRON_RLM_MAX_TREE_MEMORY_MB when it is all digits, else twice the per-process limit; 0 disables. A value past 2^53 - 1 is an error, as in TypeScript.
private_rss_bytes
processPrivateRssBytes of a /proc/<pid>/status text: RssAnon + RssShmem + VmSwap.
process_cgroup_dir
processCgroupDir: the cgroup v2 directory of pid (from its 0:: line), or none.
process_memory_bytes
processMemoryBytes: one process’s proportional memory in bytes; 0 when it is gone or a kernel thread.
proportional_bytes
processMemoryBytes of a /proc/<pid>/smaps_rollup text: Pss_Anon + Pss_Shmem + SwapPss, where a page shared by N processes counts 1/N in each; none when the rollup has no Pss_Anon (before Linux 5.9: fall back to the status).
tree_memory_backend
treeMemoryBackend: requested (ULTRON_RLM_TREE_MEMORY_BACKEND: auto|cgroup|watchdog|off) for a cap; “cgroup”, “auto” and anything unrecognized take a capped scope when cgroup_available says this system allows one, else the watchdog.
tree_memory_limit_message
treeMemoryLimitMessage: the error a kernel stopped by the tree cap reports.
tree_memory_usage
treeMemoryUsage: memory of root and its live descendant tree, with the descendants seen.
watchdog_poll_ms
watchdogPollMs: the watchdog’s next poll for a tree at bytes of a cap_bytes cap, faster near the cap.