Use as a platform-independent term to describe pidfd(Linux)/process handle (Windows)

iCharlesHu · iCharlesHu · commit 69c25d517db4 · 2025-08-11T10:54:46.000-07:00
diff --git a/Sources/Subprocess/Platforms/Subprocess+Linux.swift b/Sources/Subprocess/Platforms/Subprocess+Linux.swift
@@ -88,14 +88,14 @@ extension Configuration {
 
                 // Spawn
                 var pid: pid_t = 0
-                var processFileDescriptor: PlatformFileDescriptor = -1
+                var processDescriptor: PlatformFileDescriptor = -1
                 let spawnError: CInt = possibleExecutablePath.withCString { exePath in
                     return (self.workingDirectory?.string).withOptionalCString { workingDir in
                         return supplementaryGroups.withOptionalUnsafeBufferPointer { sgroups in
                             return fileDescriptors.withUnsafeBufferPointer { fds in
                                 return _subprocess_fork_exec(
                                     &pid,
-                                    &processFileDescriptor,
+                                    &processDescriptor,
                                     exePath,
                                     workingDir,
                                     fds.baseAddress!,
@@ -145,7 +145,7 @@ extension Configuration {
                 let execution = Execution(
                     processIdentifier: .init(
                         value: pid,
-                        processFileDescriptor: processFileDescriptor
+                        processDescriptor: processDescriptor
                     )
                 )
                 return SpawnResult(
@@ -191,16 +191,16 @@ extension Configuration {
 public struct ProcessIdentifier: Sendable, Hashable {
     /// The platform specific process identifier value
     public let value: pid_t
-    internal let processFileDescriptor: PlatformFileDescriptor
+    internal let processDescriptor: PlatformFileDescriptor
 
-    internal init(value: pid_t, processFileDescriptor: PlatformFileDescriptor) {
+    internal init(value: pid_t, processDescriptor: PlatformFileDescriptor) {
         self.value = value
-        self.processFileDescriptor = processFileDescriptor
+        self.processDescriptor = processDescriptor
     }
 
     internal func close() {
-        if self.processFileDescriptor > 0 {
-            _SubprocessCShims.close(self.processFileDescriptor)
+        if self.processDescriptor > 0 {
+            _SubprocessCShims.close(self.processDescriptor)
         }
     }
 }
@@ -304,16 +304,16 @@ internal func monitorProcessTermination(
                 // pidfd is only supported on Linux kernel 5.4 and above
                 // On older releases, use signalfd so we do not need
                 // to register anything with epoll
-                if processIdentifier.processFileDescriptor > 0 {
-                    // Register processFileDescriptor with epoll
+                if processIdentifier.processDescriptor > 0 {
+                    // Register processDescriptor with epoll
                     var event = epoll_event(
                         events: EPOLLIN.rawValue,
-                        data: epoll_data(fd: processIdentifier.processFileDescriptor)
+                        data: epoll_data(fd: processIdentifier.processDescriptor)
                     )
                     let rc = epoll_ctl(
                         storage.epollFileDescriptor,
                         EPOLL_CTL_ADD,
-                        processIdentifier.processFileDescriptor,
+                        processIdentifier.processDescriptor,
                         &event
                     )
                     if rc != 0 {
@@ -326,7 +326,7 @@ internal func monitorProcessTermination(
                     }
                     // Now save the registration
                     var newState = storage
-                    newState.continuations[processIdentifier.processFileDescriptor] = continuation
+                    newState.continuations[processIdentifier.processDescriptor] = continuation
                     state = .started(newState)
                     // No state to resume
                     return nil
@@ -342,7 +342,7 @@ internal func monitorProcessTermination(
                         if siginfo.si_pid == 0 && siginfo.si_signo == 0 {
                             // Save this continuation to be called by signal hander
                             var newState = storage
-                            newState.continuations[processIdentifier.processFileDescriptor] = continuation
+                            newState.continuations[processIdentifier.processDescriptor] = continuation
                             state = .started(newState)
                             return nil
                         }
@@ -421,7 +421,7 @@ private extension siginfo_t {
 // Okay to be unlocked global mutable because this value is only set once like dispatch_once
 private nonisolated(unsafe) var _signalPipe: (readEnd: CInt, writeEnd: CInt) = (readEnd: -1, writeEnd: -1)
 // Okay to be unlocked global mutable because this value is only set once like dispatch_once
-private nonisolated(unsafe) var _waitProcessFileDescriptorSupported = false
+private nonisolated(unsafe) var _waitprocessDescriptorSupported = false
 private let _processMonitorState: Mutex<ProcessMonitorState> = .init(.notStarted)
 
 private func shutdown() {
@@ -520,8 +520,8 @@ private func monitorThreadFunc(args: UnsafeMutableRawPointer?) -> UnsafeMutableR
             }
 
             // P_PIDFD requires Linux Kernel 5.4 and above
-            if _waitProcessFileDescriptorSupported {
-                _blockAndWaitForProcessFileDescriptor(targetFileDescriptor, context: context)
+            if _waitprocessDescriptorSupported {
+                _blockAndWaitForprocessDescriptor(targetFileDescriptor, context: context)
             } else {
                 _reapAllKnownChildProcesses(targetFileDescriptor, context: context)
             }
@@ -573,7 +573,7 @@ private let setup: () = {
 
     // If the current kernel does not support pidfd, fallback to signal handler
     // Create the self-pipe that signal handler writes to
-    if !_isWaitProcessFileDescriptorSupported() {
+    if !_isWaitprocessDescriptorSupported() {
         var pipeCreationError: SubprocessError? = nil
         do {
             let (readEnd, writeEnd) = try FileDescriptor.pipe()
@@ -612,7 +612,7 @@ private let setup: () = {
         }
     } else {
         // Mark waitid(P_PIDFD) as supported
-        _waitProcessFileDescriptorSupported = true
+        _waitprocessDescriptorSupported = true
     }
     let monitorThreadContext = MonitorThreadContext(
         epollFileDescriptor: epollFileDescriptor,
@@ -645,7 +645,7 @@ private func _setupMonitorSignalHandler() {
     setup
 }
 
-private func _blockAndWaitForProcessFileDescriptor(_ pidfd: CInt, context: MonitorThreadContext) {
+private func _blockAndWaitForprocessDescriptor(_ pidfd: CInt, context: MonitorThreadContext) {
     var terminationStatus: Result<TerminationStatus, SubprocessError>
 
     var siginfo = siginfo_t()
@@ -760,7 +760,7 @@ private func _reapAllKnownChildProcesses(_ signalFd: CInt, context: MonitorThrea
     }
 }
 
-internal func _isWaitProcessFileDescriptorSupported() -> Bool {
+internal func _isWaitprocessDescriptorSupported() -> Bool {
     // waitid(P_PIDFD) is only supported on Linux kernel 5.4 and above
     // Prob whether the current system supports it by calling it with self pidfd
     // and checking for EINVAL (waitid sets errno to EINVAL if it does not
diff --git a/Sources/Subprocess/Platforms/Subprocess+Unix.swift b/Sources/Subprocess/Platforms/Subprocess+Unix.swift
@@ -117,7 +117,7 @@ extension Execution {
             try _kill(pid, signal: signal)
         } else {
             guard _pidfd_send_signal(
-                processIdentifier.processFileDescriptor,
+                processIdentifier.processDescriptor,
                 signal.rawValue
             ) == 0 else {
                 throw SubprocessError(
diff --git a/Sources/Subprocess/Platforms/Subprocess+Windows.swift b/Sources/Subprocess/Platforms/Subprocess+Windows.swift
@@ -136,7 +136,7 @@ extension Configuration {
 
         let pid = ProcessIdentifier(
             value: processInfo.dwProcessId,
-            processHandle: processInfo.hProcess,
+            processDescriptor: processInfo.hProcess,
             threadHandle: processInfo.hThread
         )
         let execution = Execution(
@@ -280,7 +280,7 @@ extension Configuration {
 
         let pid = ProcessIdentifier(
             value: processInfo.dwProcessId,
-            processHandle: processInfo.hProcess,
+            processDescriptor: processInfo.hProcess,
             threadHandle: processInfo.hThread
         )
         let execution = Execution(
@@ -487,7 +487,7 @@ internal func monitorProcessTermination(
         guard
             RegisterWaitForSingleObject(
                 &waitHandle,
-                processIdentifier.processHandle,
+                processIdentifier.processDescriptor,
                 callback,
                 context,
                 INFINITE,
@@ -505,7 +505,7 @@ internal func monitorProcessTermination(
     }
 
     var status: DWORD = 0
-    guard GetExitCodeProcess(processIdentifier.processHandle, &status) else {
+    guard GetExitCodeProcess(processIdentifier.processDescriptor, &status) else {
         // The child process terminated but we couldn't get its status back.
         // Assume generic failure.
         return .exited(1)
@@ -523,7 +523,7 @@ extension Execution {
     /// Terminate the current subprocess with the given exit code
     /// - Parameter exitCode: The exit code to use for the subprocess.
     public func terminate(withExitCode exitCode: DWORD) throws {
-        guard TerminateProcess(self.processIdentifier.processHandle, exitCode) else {
+        guard TerminateProcess(self.processIdentifier.processDescriptor, exitCode) else {
             throw SubprocessError(
                 code: .init(.failedToTerminate),
                 underlyingError: .init(rawValue: GetLastError())
@@ -547,7 +547,7 @@ extension Execution {
                 underlyingError: .init(rawValue: GetLastError())
             )
         }
-        guard NTSuspendProcess(self.processIdentifier.processHandle) >= 0 else {
+        guard NTSuspendProcess(self.processIdentifier.processDescriptor) >= 0 else {
             throw SubprocessError(
                 code: .init(.failedToSuspend),
                 underlyingError: .init(rawValue: GetLastError())
@@ -571,7 +571,7 @@ extension Execution {
                 underlyingError: .init(rawValue: GetLastError())
             )
         }
-        guard NTResumeProcess(self.processIdentifier.processHandle) >= 0 else {
+        guard NTResumeProcess(self.processIdentifier.processDescriptor) >= 0 else {
             throw SubprocessError(
                 code: .init(.failedToResume),
                 underlyingError: .init(rawValue: GetLastError())
@@ -677,21 +677,21 @@ extension Environment {
 public struct ProcessIdentifier: Sendable, Hashable {
     /// Windows specific process identifier value
     public let value: DWORD
-    internal nonisolated(unsafe) let processHandle: HANDLE
+    internal nonisolated(unsafe) let processDescriptor: HANDLE
     internal nonisolated(unsafe) let threadHandle: HANDLE
 
 
-    internal init(value: DWORD, processHandle: HANDLE, threadHandle: HANDLE) {
+    internal init(value: DWORD, processDescriptor: HANDLE, threadHandle: HANDLE) {
         self.value = value
-        self.processHandle = processHandle
+        self.processDescriptor = processDescriptor
         self.threadHandle = threadHandle
     }
 
     internal func close() {
         guard CloseHandle(self.threadHandle) else {
             fatalError("Failed to close thread HANDLE: \(SubprocessError.UnderlyingError(rawValue: GetLastError()))")
         }
-        guard CloseHandle(self.processHandle) else {
+        guard CloseHandle(self.processDescriptor) else {
             fatalError("Failed to close process HANDLE: \(SubprocessError.UnderlyingError(rawValue: GetLastError()))")
         }
     }
diff --git a/Sources/_SubprocessCShims/process_shims.c b/Sources/_SubprocessCShims/process_shims.c
@@ -540,12 +540,18 @@ int _subprocess_fork_exec(
         // If we reached this point, something went wrong
         write_error_and_exit;
     } else {
+#define reap_child_process_and_return_errno int capturedError = errno; \
+    close(pipefd[0]); \
+    siginfo_t info; \
+    waitid(P_PID, childPid, &info, WEXITED); \
+    return capturedError
+
         // On Linux 5.3 and lower, we have to fetch pidfd separately
         // Newer Linux supports clone3 which returns pidfd directly
         if (_pidfd < 0) {
             _pidfd = _pidfd_open(childPid);
             if (_pidfd < 0) {
-                return errno;
+                reap_child_process_and_return_errno;
             }
         }
 
@@ -555,8 +561,7 @@ int _subprocess_fork_exec(
         // Restore old signmask
         rc = pthread_sigmask(SIG_SETMASK, &old_sigmask, NULL);
         if (rc != 0) {
-            close(pipefd[0]);
-            return errno;
+            reap_child_process_and_return_errno;
         }
 
         // Unlock
