Introduce process file descriptor (pidfd) based process monitoring for Linux #125

iCharlesHu · 2025-07-16T22:01:11Z

The current process monitoring code for Linux has a flaw that makes it susceptible to infinite hangs under specific conditions:

The parent process uses any other method (other than Subprocess itself) to spawn new processes in addition to spawning with Subprocess.
The parent process fails to properly reap the non-Subprocess-spawned process, leaving it as a zombie in the process table.

This is because currently, we rely on running waitid() with P_ALL and WNOWAIT in an infinite loop to detect possible child process state transitions. However, we don’t reap the child process (by specifying WNOWAIT) unless we (Subprocess) actually spawned the process.

Here’s a simplified pseudo-code to illustrate the issue:

while true {
    var siginfo = siginfo_t()
    // We’re not reaping the child process
    if waitid(P_ALL, id_t(0), &siginfo, WEXITED | WNOWAIT) == 0 {
        guard let c = savedContinuation else {
            // If there’s no saved continuation, we didn’t spawn the process
            // In this case, we don’t reap the child process
            continue
        }

        siginfo = siginfo_t()
        waitid(P_PID, numericCast(pid), &siginfo, WEXITED) // We’re actually reaping the child process
    }
}

With this setup, if there are zombie children in the process table without reaping, waitid(P_ALL) will repeatedly return the same (non-Subprocess-spawned) PID with every call, causing an infinite loop.

You can observe this behavior with the following sample code:

let arguments = "\"\""

let pid = arguments.withCString { args in
    var pid: pid_t = -1
    let status = posix_spawn(&pid, "/bin/echo", nil, nil, [strdup(args)] + [nil], environ)
    guard status == 0 else {
        fatalError("posix_spawn: \(status), errno: \(errno)")
    }
    return pid
}
print("echo pid: \(pid)")

let result = try await Subprocess.run(
    .path("/bin/cat"),
    arguments: ["Package.swift"],
    output: .string(limit: .max, encoding: UTF8.self),
    error: .discarded
)
print("cat finished: \(result.terminationStatus)")
print("cat output: \(result.standardOutput ?? "")")

After running this example, you’ll notice that the parent process seems to be stuck, and the “cat finished” message is never printed. This is because the parent process never calls waitid on the echo call, leaving it in the process table. Consequently, the monitor thread runs in an infinite loop.

While some may argue that this is not a bug in Subprocess, but rather an issue with the parent code, since the POSIX standard mandates that the process spawning child process must reap the child process via waitid. However, Subprocess should still not hang due to someone else’s bug.

To resolve this issue, switch to a Linux-specific process monitoring method by creating and observing the process file descriptor (pidfd) using epoll. This approach is similar to the epoll implementation introduced in #117, with the only difference being that we’re polling pidfd instead of a regular file descriptor.

As part of this change, I also unified the “process handle” design to make it easier to expose process handles to clients later (after the 1.0 release, as requested by #101). We chose to use ProcessIdentifier to host platform-specific process file descriptors and process handles because it perfectly aligns with the original use case. To ensure flexibility, we opted for a concrete ProcessIdentifier type instead of just a number, allowing us to add more information if necessary.

…r Linux

iCharlesHu · 2025-07-16T22:01:38Z

Resolves #111

iCharlesHu · 2025-07-16T22:27:25Z

waitid with P_PIDFD was introduced in Linux kernel 5.4, which focal should have. I'm looking into what's missing

cthielen · 2025-07-16T22:10:56Z