Report the sampled peak memory of the whole process tree

[janedbal]

#6297 replaced the summed fiction with two per-process figures that the OS can confirm. This adds the third number people keep asking for — how much memory the whole run took — without bringing the fiction back:

Peak memory: 342.5 MB (main process), 220 MB (largest of 20 forked workers)
Total peak memory: 3.67 GB (all processes combined, sampled)

Why the per-process figures cannot just be added up

A forked worker shares its inherited pages with the main process and every sibling copy-on-write. Each process's RSS counts a shared physical page again, so a sum across the tree multiplies it by the process count — that multiplication is exactly what made the old Used memory line explode under forking.

The kernel already has the number that adds up: PSS divides every physical page among the processes that share it, so the PSS of the tree summed across its processes is the tree's actual footprint at that instant. That covers the turbo arena too — a /dev/shm mapping shared by all workers is split among them the same way. /proc/<pid>/smaps_rollup serves the per-process total without walking the full smaps listing, and reading it needs no privileges for direct children — spawned workers included.

How the peak is taken

The kernel keeps no PSS high-water mark, so the peak has to be sampled: the main process reads every process's rollup twice per second on its existing event loop and keeps the largest sum. Sampling only starts at -v and above — the only place the line prints — so a quiet run pays nothing.

Both gaps of sampling understate, never exaggerate:

• A spike between two samples is missed.
• The main process's own late peak — collecting worker results, saving the result cache — comes after the workers are gone and the event loop with them, so no sample sees it. getPeakBytes() closes that gap with the main process's VmHWM, its lifetime RSS high-water mark: a process's RSS never exceeds the tree's physical footprint at the same instant, so VmHWM is itself a lower bound of the tree's peak, and taking the larger of the two bounds only tightens the estimate.

On platforms without /proc (Windows, macOS) nothing is sampled and the line is not printed, same as the cgroup-based CPU detection behaves there.

Checked against the OS

Cold self-analysis of this repository, 20 forked workers, with an external observer polling smaps_rollup of the whole process tree at 5 Hz:

printed Total peak memory	3.67 GB
observer: max sum of PSS	3.66 GB
observer: max sum of RSS (the naive total)	4.83 GB

Spawn mode (pcntl disabled) prints and validates the same way.

The tracker follows the SystemResources pattern — a $filesystemRoot constructor argument lets the tests run against fixture /proc trees; five of them cover the sum, the peak-keeps-the-largest-sample behavior, an exited worker mid-sample, the VmHWM lift, and the no-/proc platform.

Co-Authored-By: Claude Code

[phpstan-bot]

This pull request has been marked as ready for review.

[ondrejmirtes]

We could skip this altogether for non-Linux systems. Otherwise it repeats to read a non-existent file every .5 seconds.

[janedbal]

Thanks for the review! I believe the repeated reads are already avoided, but I may have hidden it too well.

start() probes /proc/self/smaps_rollup once before it registers the timer. When that file cannot be read, the method returns early and no periodic timer is created. On macOS and Windows that means exactly one failed file_get_contents() per run, not one every 0.5 seconds. getPeakBytes() then returns null because nothing was sampled, and InceptionResult prints nothing.

I went with a probe instead of PHP_OS_FAMILY === 'Linux' because the file can also be missing on Linux: kernels before 4.14 have no smaps_rollup, and /proc mounted with hidepid hides the worker directories. The probe covers those cases too.

If you prefer the intent to be explicit, I can add the PHP_OS_FAMILY check in front of the probe so a reader sees the platform gate right away. Happy to do either, just say which.

Claude