Files
DroidDeck/docs/development/phantom-processes.md
T
MaxsTechReview 4527e93118 docs(phantom): how Android counts guest processes and why detaching cannot escape it (#2584)
* docs(phantom): how Android counts guest processes and why detaching cannot escape it

* docs(phantom): clarify probe permissions and batch capture

* docs(phantom): qualify probe precondition by SDK and size the limit device-wide

* docs(phantom): keep phantom discovery on for the 12L probe and raise the limit instead

* docs(phantom): warn about the CPU kill, raise the limit before the flag and restore both after the probe

* docs(phantom): restore the monitor flag before the phantom limit after the probe

* docs(phantom): restore the flag before the limit whether each is put or deleted
2026-11-15 09:37:34 -05:00

11 KiB

Android's child-process limit and the guest session

Since Android 12 the platform counts the processes an app forks as "phantom processes" and kills them under pressure. A Wine, FEX or Steam session forks dozens of them, so this limit decides whether a session survives. This note records how the platform counts, what it kills, why the guest cannot leave the count, and what DroidDeck changes on the device.

What the platform counts

Discovery is a cgroup scan, not a parent-child relation. For every app process the platform knows, it reads the cgroup member list of that process and takes every pid that is not a known app process as a phantom of it:

  • frameworks/base/services/core/java/com/android/server/am/PhantomProcessList.java:117-122 holds the two cgroup roots (/acct/uid_ for cgroup v1, /sys/fs/cgroup/uid_ for v2) and the cgroup.procs file name.
  • PhantomProcessList.java:136-208 scans every app process; :220-222 builds the path /…/uid_<uid>/pid_<appPid>/cgroup.procs; :238-275 turns a pid that is not a known app process into a phantom of that app process.
  • The mechanism is the same in Android 12.0, 12.1, 13, 14, 15, 16 and in main. Only the path lookup moved to a native helper in 16 and main (PhantomProcessList.java:205).

DroidDeck's guest is forked by the main app process: SessionService starts it with HostProcess.start (app/src/main/java/com/droiddeck/launcher/session/SessionService.kt:779), and both SessionService and SessionActivity run in the main process (app/src/main/AndroidManifest.xml:284-293, :326-329). Every guest process is therefore a phantom of the main app process.

What the platform kills

  1. Count trim. When the number of phantom processes in the system passes MAX_PHANTOM_PROCESSES (32 by default, ActivityManagerConstants.java:192), the surplus is killed, starting with the phantoms whose parent app has the least importance (PhantomProcessList.java:423-466).
  2. Excessive CPU group kill. Every five minutes the platform measures each app's CPU use. For an app whose process state is HOME or less important (backgrounded), a phantom process that used more than its threshold (25, 25, 10 or 2 percent) is killed together with its phantom siblings and the app process itself (ActivityManagerService.java:16114-16152, PhantomProcessList.java:496-515). A foreground DroidDeck is exempt; a backgrounded one is not.

The second path is the one that ends a session without an error message in the guest log: the app process dies with it.

The gate, and how the versions differ

Both paths are behind the feature flag settings_enable_monitor_phantom_procs, whose default is on. The flag is read from Settings.Global first (frameworks/base/core/java/android/util/FeatureFlagUtils.java:68-70, :272-283). When it is off, the trim returns early (PhantomProcessList.java:423-427) and the phantom CPU check is skipped (ActivityManagerService.java:16117-16118, :16144-16148). From 12L on it also stops the periodic cgroup scan that discovers phantom processes (AppProfiler.java:1788-1829 at android-12.1.0_r1).

Android flag settings_enable_monitor_phantom_procs count limit CPU group kill
12.0 (SDK 31) does not exist DeviceConfig activity_manager/max_phantom_processes, default 32 not gated
12L (SDK 32) exists flag flag
13 and later (SDK 33+) exists flag flag

The flag was added in 12.1. On 12.0 the count limit comes from DeviceConfig (ActivityManagerConstants.java:1202-1206 in 12.0) and the CPU group kill has no gate at all (ActivityManagerService.java:14237-14271 in 12.0).

Why the guest cannot leave the count

  • Reparenting does not help. A double fork, setsid() or an orphaning parent changes the parent and the session, not the cgroup. Cgroup membership is inherited at fork and only a write into another cgroup's cgroup.procs changes it, so the platform still finds the pid in the app process's cgroup and still counts it. On cgroup v2 the uid group cannot take processes while it has the per-process groups as children, so there is no unscanned group to move into.
  • A separate :process service only moves the count. The scan covers every app process the platform knows, so the guest tree started from another service of the same app is counted against that service. The manifest already has such services (app/src/main/AndroidManifest.xml:78, :244, :255), and the guest tree is one coupled userspace whose graphics, input and session state would not survive the split.
  • The platform's own blind spot is out of reach. Processes forked from an app zygote are skipped by the scan (PhantomProcessList.java:153-155), but android.os.AppZygote is @hide (frameworks/base/core/java/android/os/AppZygote.java:36-38) and hidden API enforcement keeps it away from apps.
  • Detaching would break the session. The guest tree is deliberately kept under a reaper: the processes that load the session library mark themselves as child subreapers, so that a double-forked Xwayland is reparented inside the session instead of to init, where a vendor kernel's orphan reaper would kill it (tools/linuxfs/preload/subreaper.c:1-16). A guest tree that leaves the app's process tree leaves that arrangement with nothing to reap it.

What DroidDeck changes on the device

PhantomProcessLimit (app/src/main/java/com/droiddeck/launcher/core/PhantomProcessLimit.kt) holds the platform lever per version: the DeviceConfig count limit on SDK 31 and the flag from SDK 32 up (:23-37). WirelessAdbFix (app/src/main/java/com/droiddeck/launcher/core/WirelessAdbFix.kt:219-228) runs those shell commands over wireless debugging when the user has no computer at hand, and the gate screen shows the result. The names on that screen come from strings.xml (phantom_title_on "Child-process limit is on", phantom_instructions_fix, phantom_fix_toggle).

The remaining gap on Android 12.0

On SDK 31 the count trim is covered by the DeviceConfig write, but the backgrounded CPU group kill is not: the flag does not exist there, and the CPU thresholds live in the global string activity_manager_constants (power_check_max_cpu_1 … power_check_max_cpu_4), not in DeviceConfig. In 12.0 the DeviceConfig listener reacts to max_phantom_processes only (ActivityManagerConstants.java:654-757), while the thresholds are parsed from Settings.Global activity_manager_constants (:852-892). Raising them means rewriting that global string, which changes the CPU kill thresholds for every app on the device. That is a trade the developers have to accept; DroidDeck does not do it on its own.

Probe to run on hardware

The mechanism above is source-verified. The probe below settles the two points a source read cannot: what a device actually does with detached children, and whether the app uid may write another cgroup's cgroup.procs. It needs a device with the guest running.

Precondition: keep settings_enable_monitor_phantom_procs enabled on Android 12L (SDK 32) and later, because disabling it also stops the cgroup scan, so no snapshot would discover either batch (AppProfiler.java:1788-1829 at android-12.1.0_r1). Android 12.0 (SDK 31) has no such flag and scans unconditionally (AppProfiler.java:1833-1834 at android-12.0.0_r1). An enabled flag, and every 12.0 device, also keeps the backgrounded CPU group kill active, which can end the guest together with the app process (see "What the platform kills", item 2). Keep DroidDeck in the foreground and stop CPU-intensive guest programs before the probe.

The limit counts phantom processes of every app on the device, not only the probe's, so raise it before anything can trim. Record the current flag and limit values first. Then raise max_phantom_processes well above any plausible device-wide count, and only after that enable the flag if it was disabled, because a flag enabled under the default limit of 32 can trim existing phantoms of every app at once. Wait for the platform to discover the existing phantoms, read the device-wide phantom count, and check that the limit is above that count, plus both batches (80), plus headroom for processes the guest and other apps start meanwhile; raise it again if not. With the limit at its default, starting 80 long-lived processes can trigger the platform trim and disrupt the guest session and processes of other apps. Restore the recorded values once the probe processes have exited, in reverse order: the flag first, then the limit, because lowering the limit schedules a trim that is skipped only while the flag is disabled.

Run the sleep loops from the app's own shell so the children run under the app uid. Run each dumpsys activity processes snapshot from an authorized ADB shell, because the app uid normally cannot read that dump. After each batch, record the child PIDs and wait long enough for the platform to discover them before taking the snapshot.

# record the current values
adb shell settings get global settings_enable_monitor_phantom_procs
adb shell device_config get activity_manager max_phantom_processes

# raise the limit first, then enable the flag on SDK 32 and later
adb shell device_config put activity_manager max_phantom_processes 1000
adb shell settings put global settings_enable_monitor_phantom_procs true
# after platform discovery: device-wide phantom count
adb shell 'dumpsys activity processes | grep -i -n -A 5 phantom'

# from the app's own shell: attached children
for i in $(seq 1 40); do sleep 600 & echo $!; done
# from an authorized ADB shell, after platform discovery
adb shell 'dumpsys activity processes | grep -i -n -A 5 phantom'

# from the app's own shell: detached children
# (the middle process exits, so the child is reparented to init)
for i in $(seq 1 40); do ( setsid sleep 600 & echo $! ) ; done
# from an authorized ADB shell, after platform discovery
adb shell 'dumpsys activity processes | grep -i -n -A 5 phantom'

# from the app's own shell
cat /proc/<appPid>/cgroup

# whether the uid may move a child out of the scanned cgroup
echo <childPid> > /sys/fs/cgroup/uid_<uid>/cgroup.procs

# from the app's own shell: end the probe processes
kill <childPids>
# restore the flag first: put the recorded value, or delete the key if it was "null"
adb shell settings put global settings_enable_monitor_phantom_procs <recordedFlag>
adb shell settings delete global settings_enable_monitor_phantom_procs
# then the limit: put the recorded value, or delete the key if it was "null"
adb shell device_config put activity_manager max_phantom_processes <recordedLimit>
adb shell device_config delete activity_manager max_phantom_processes

Compare the PIDs recorded for each batch with the phantom list in the snapshot taken after that batch. Expected from the source: both batches are counted, the detached ones included, and the cgroup write fails (no unscanned group, or no permission).

References

  • AOSP frameworks/base: services/core/java/com/android/server/am/PhantomProcessList.java, services/core/java/com/android/server/am/ActivityManagerService.java, services/core/java/com/android/server/am/ActivityManagerConstants.java, core/java/android/util/FeatureFlagUtils.java, checked at tags android-12.0.0_r1, android-12.1.0_r1, android-13.0.0_r1, android-14.0.0_r2, android-15.0.0_r1, android-16.0.0_r1 and main.
  • Pull request 1394, the OEM check of the same settings, and the issues it links, 713 and 1083.
  • Termux meets the same limit on Android 12 and solves it the same way, with detection plus the adb path (termux-app issues 4388 and 4857).