Add ResourceUsage to report subprocess CPU time and memory consumption

Introduce a public ResourceUsage struct that exposes userTime, systemTime
(as Duration), and maxRSS (in bytes) for every terminated subprocess.
An ExecutionResult protocol provides common access to terminationStatus
and resourceUsage across both ExecutionOutcome and ExecutionRecord.

On Unix, resource data is collected via wait4 (BSD) or the Linux kernel's
5-argument waitid syscall, which populates a rusage struct alongside the
termination status. A linux_waitid C shim is added because glibc and musl
only expose the 4-parameter POSIX waitid that omits rusage. The raw
rusage is available as a public property on non-Windows platforms, with
maxRSS normalized from KiB to bytes on Linux, FreeBSD, and OpenBSD.

On Windows, GetProcessTimes provides CPU time (converted from FILETIME
100ns units) and GetProcessMemoryInfo provides PeakWorkingSetSize (maxRSS).

This functionality is particularly necessary as part of SwiftSubprocess
because collecting rusage information from a terminated subprocess requires
the ability to run code when a process has changed state from executing
to zombie, but before its pid has been reaped - something not possible
with the current Subprocess API. Further, it is notoriously difficult
to collect this information across all OSes for an arbitrary PID anyways,
at least in a way that doesn't also simultaneously reap the pid.
User time, system time, and maxRSS are some of the most common metrics
typically extracted from getrusage. Exposing the raw rusage struct
provides access to the rest, and on Windows, callers can use DuplicateHandle
to get a process descriptor that can outlive Subprocess's control of the
process and collect any additional metrics from the process when it is
known to be in a terminated state.

Author: jakepetroules

Sources/Subprocess/API.swift

@@ -440,6 +440,7 @@ public func run<
     return ExecutionRecord(
         processIdentifier: result.value.processIdentifier,
         terminationStatus: result.terminationStatus,
+        resourceUsage: result.resourceUsage,
         standardOutput: result.value.standardOutput,
         standardError: result.value.standardError
     )
@@ -544,6 +545,7 @@ public func run<
     return ExecutionRecord(
         processIdentifier: result.value.processIdentifier,
         terminationStatus: result.terminationStatus,
+        resourceUsage: result.resourceUsage,
         standardOutput: result.value.standardOutput,
         standardError: result.value.standardError
     )

Sources/Subprocess/Configuration.swift

@@ -134,12 +134,13 @@ public struct Configuration: Sendable {
             // even if `body` throws, and we are not leaving zombie processes in the
             // process table which will cause the process termination monitoring thread
             // to effectively hang due to the pid never being awaited
-            let terminationStatus = try await monitorProcessTermination(
+            let (terminationStatus, resourceUsage) = try await monitorProcessTermination(
                 for: execution.processIdentifier
             )
 
             return ExecutionOutcome(
                 terminationStatus: terminationStatus,
+                resourceUsage: resourceUsage,
                 value: try result.get()
             )
         } onCleanup: {

Sources/Subprocess/Platforms/Subprocess+BSD.swift

@@ -29,10 +29,10 @@ internal import Dispatch
 @Sendable
 internal func monitorProcessTermination(
     for processIdentifier: ProcessIdentifier
-) async throws(SubprocessError) -> TerminationStatus {
-    switch Result(catching: { () throws(Errno) -> TerminationStatus? in try processIdentifier.reap() }) {
-    case let .success(status?):
-        return status
+) async throws(SubprocessError) -> (TerminationStatus, ResourceUsage) {
+    switch Result(catching: { () throws(Errno) -> (TerminationStatus, ResourceUsage)? in try processIdentifier.reap() }) {
+    case let .success(result?):
+        return result
     case .success(nil):
         break
     case let .failure(error):
@@ -50,10 +50,9 @@ internal func monitorProcessTermination(
 
                 do throws(Errno) {
                     // NOTE_EXIT may be delivered slightly before the process becomes reapable,
-                    // so we must call waitid without WNOHANG to avoid a narrow possibility of a race condition.
-                    // If waitid does block, it won't do so for very long at all.
-                    let status = try processIdentifier.blockingReap()
-                    continuation.resume(returning: status)
+                    // so we must call wait4 without WNOHANG to avoid a narrow possibility of a race condition.
+                    // If wait4 does block, it won't do so for very long at all.
+                    continuation.resume(returning: try processIdentifier.blockingReap())
                 } catch {
                     let subprocessError: SubprocessError = .failedToMonitor(withUnderlyingError: error)
                     continuation.resume(throwing: subprocessError)

Sources/Subprocess/Platforms/Subprocess+Linux.swift

@@ -79,10 +79,10 @@ extension Int32 {
 @Sendable
 internal func monitorProcessTermination(
     for processIdentifier: ProcessIdentifier
-) async throws(SubprocessError) -> TerminationStatus {
+) async throws(SubprocessError) -> (TerminationStatus, ResourceUsage) {
     return try await _castError {
         return try await withCheckedThrowingContinuation { continuation in
-            let status = _processMonitorState.withLock { state -> Result<TerminationStatus, SubprocessError>? in
+            let status = _processMonitorState.withLock { state -> Result<(TerminationStatus, ResourceUsage), SubprocessError>? in
                 switch state {
                 case .notStarted:
                     let error: SubprocessError = .failedToMonitor(withUnderlyingError: nil)
@@ -123,9 +123,9 @@ internal func monitorProcessTermination(
                         // Since Linux coalesce signals, it's possible by the time we request
                         // monitoring the process has already exited. Check to make sure that
                         // is not the case and only save continuation then.
-                        switch Result(catching: { () throws(Errno) -> TerminationStatus? in try processIdentifier.reap() }) {
-                        case let .success(status?):
-                            return .success(status)
+                        switch Result(catching: { () throws(Errno) -> (TerminationStatus, ResourceUsage)? in try processIdentifier.reap() }) {
+                        case let .success(result?):
+                            return .success(result)
                         case .success(nil):
                             // Save this continuation to be called by signal handler
                             var newState = storage
@@ -158,7 +158,7 @@ private enum ProcessMonitorState {
         let epollFileDescriptor: CInt
         let shutdownFileDescriptor: CInt
         let monitorThread: pthread_t
-        var continuations: [PlatformFileDescriptor: CheckedContinuation<TerminationStatus, any Error>]
+        var continuations: [PlatformFileDescriptor: CheckedContinuation<(TerminationStatus, ResourceUsage), any Error>]
     }
 
     case notStarted
@@ -243,8 +243,8 @@ private func monitorThreadFunc(context: MonitorThreadContext) {
             let error: SubprocessError = .failedToMonitor(
                 withUnderlyingError: Errno(rawValue: pwaitErrno)
             )
-            let continuations = _processMonitorState.withLock { state -> [CheckedContinuation<TerminationStatus, any Error>] in
-                let result: [CheckedContinuation<TerminationStatus, any Error>]
+            let continuations = _processMonitorState.withLock { state -> [CheckedContinuation<(TerminationStatus, ResourceUsage), any Error>] in
+                let result: [CheckedContinuation<(TerminationStatus, ResourceUsage), any Error>]
                 if case .started(let storage) = state {
                     result = Array(storage.continuations.values)
                 } else {
@@ -407,8 +407,17 @@ internal func _setupMonitorSignalHandler() {
 }
 
 private func _blockAndWaitForProcessDescriptor(_ pidfd: CInt, context: MonitorThreadContext) {
-    var terminationStatus = Result(catching: { () throws(Errno) in
-        try TerminationStatus(_waitid(idtype: idtype_t(UInt32(P_PIDFD)), id: id_t(pidfd), flags: WEXITED))
+    var terminationResult = Result(catching: { () throws(Errno) -> (TerminationStatus, ResourceUsage) in
+        while true {
+            var siginfo = siginfo_t()
+            var usage = rusage()
+            let rc = linux_waitid(idtype_t(UInt32(P_PIDFD)), id_t(pidfd), &siginfo, WEXITED, &usage)
+            if rc != -1 {
+                return (TerminationStatus(siginfo), ResourceUsage(usage))
+            } else if errno != EINTR {
+                throw Errno(rawValue: errno)
+            }
+        }
     }).mapError { underlyingError in
         return SubprocessError.failedToMonitor(withUnderlyingError: underlyingError)
     }
@@ -422,14 +431,14 @@ private func _blockAndWaitForProcessDescriptor(_ pidfd: CInt, context: MonitorTh
     )
     if rc != 0 {
         let epollErrno = errno
-        terminationStatus = .failure(
+        terminationResult = .failure(
             SubprocessError.failedToMonitor(
                 withUnderlyingError: Errno(rawValue: epollErrno)
             )
         )
     }
     // Notify the continuation
-    let continuation = _processMonitorState.withLock { state -> CheckedContinuation<TerminationStatus, any Error>? in
+    let continuation = _processMonitorState.withLock { state -> CheckedContinuation<(TerminationStatus, ResourceUsage), any Error>? in
         guard case .started(let storage) = state,
             let continuation = storage.continuations[pidfd]
         else {
@@ -441,13 +450,13 @@ private func _blockAndWaitForProcessDescriptor(_ pidfd: CInt, context: MonitorTh
         state = .started(newStorage)
         return continuation
     }
-    continuation?.resume(with: terminationStatus)
+    continuation?.resume(with: terminationResult)
 }
 
 // On older kernels, fall back to using signal handlers
 private typealias ResultContinuation = (
-    result: Result<TerminationStatus, SubprocessError>,
-    continuation: CheckedContinuation<TerminationStatus, any Error>
+    result: Result<(TerminationStatus, ResourceUsage), SubprocessError>,
+    continuation: CheckedContinuation<(TerminationStatus, ResourceUsage), any Error>
 )
 private func _reapAllKnownChildProcesses(_ signalFd: CInt, context: MonitorThreadContext) {
     guard signalFd == _signalPipe.readEnd else {
@@ -467,19 +476,19 @@ private func _reapAllKnownChildProcesses(_ signalFd: CInt, context: MonitorThrea
         // Since Linux coalesce signals, we need to loop through all known child process
         // to check if they exited.
         loop: for (knownChildPID, continuation) in storage.continuations {
-            let terminationStatus: Result<TerminationStatus, SubprocessError>
-            switch Result(catching: { () throws(Errno) -> TerminationStatus? in try _reap(pid: knownChildPID) }) {
-            case let .success(status?):
-                terminationStatus = .success(status)
+            let terminationResult: Result<(TerminationStatus, ResourceUsage), SubprocessError>
+            switch Result(catching: { () throws(Errno) -> (TerminationStatus, ResourceUsage)? in try _reap(pid: knownChildPID) }) {
+            case let .success(result?):
+                terminationResult = .success(result)
             case .success(nil):
                 // Move on to the next child
                 continue loop
             case let .failure(error):
-                terminationStatus = .failure(
+                terminationResult = .failure(
                     SubprocessError.failedToMonitor(withUnderlyingError: error)
                 )
             }
-            results.append((result: terminationStatus, continuation: continuation))
+            results.append((result: terminationResult, continuation: continuation))
             // Now we have the exit code, remove saved continuations
             updatedContinuations.removeValue(forKey: knownChildPID)
         }

Sources/Subprocess/Platforms/Subprocess+Unix.swift

@@ -673,37 +673,63 @@ extension PlatformOptions: CustomStringConvertible, CustomDebugStringConvertible
 extension ProcessIdentifier {
     /// Reaps the zombie for the exited process. This function may block.
     @available(*, noasync)
-    internal func blockingReap() throws(Errno) -> TerminationStatus {
+    internal func blockingReap() throws(Errno) -> (TerminationStatus, ResourceUsage) {
         try _blockingReap(pid: value)
     }
 
     /// Reaps the zombie for the exited process, or returns `nil` if the process is still running. This function will not block.
-    internal func reap() throws(Errno) -> TerminationStatus? {
+    internal func reap() throws(Errno) -> (TerminationStatus, ResourceUsage)? {
         try _reap(pid: value)
     }
 }
 
 @available(*, noasync)
-internal func _blockingReap(pid: pid_t) throws(Errno) -> TerminationStatus {
-    let siginfo = try _waitid(idtype: P_PID, id: id_t(pid), flags: WEXITED)
-    return TerminationStatus(siginfo)
-}
-
-internal func _reap(pid: pid_t) throws(Errno) -> TerminationStatus? {
-    let siginfo = try _waitid(idtype: P_PID, id: id_t(pid), flags: WEXITED | WNOHANG)
-    // If si_pid and si_signo are both 0, the child is still running since we used WNOHANG
-    if siginfo.si_pid == 0 && siginfo.si_signo == 0 {
-        return nil
+internal func _blockingReap(pid: pid_t) throws(Errno) -> (TerminationStatus, ResourceUsage) {
+    while true {
+        var usage = rusage()
+        #if os(macOS) || os(FreeBSD) || os(OpenBSD)
+        var status: CInt = 0
+        let rc = wait4(pid, &status, 0, &usage)
+        #elseif os(Linux) || os(Android)
+        var siginfo = siginfo_t()
+        let rc = linux_waitid(P_PID, id_t(pid), &siginfo, WEXITED, &usage)
+        #endif
+        if rc >= 0 {
+            #if os(macOS) || os(FreeBSD) || os(OpenBSD)
+            return (TerminationStatus(waitStatus: status), ResourceUsage(usage))
+            #elseif os(Linux) || os(Android)
+            return (TerminationStatus(siginfo), ResourceUsage(usage))
+            #endif
+        } else if errno != EINTR {
+            throw Errno(rawValue: errno)
+        }
     }
-    return TerminationStatus(siginfo)
 }
 
-internal func _waitid(idtype: idtype_t, id: id_t, flags: Int32) throws(Errno) -> siginfo_t {
+internal func _reap(pid: pid_t) throws(Errno) -> (TerminationStatus, ResourceUsage)? {
     while true {
+        var usage = rusage()
+        #if os(macOS) || os(FreeBSD) || os(OpenBSD)
+        var status: CInt = 0
+        let rc = wait4(pid, &status, WNOHANG, &usage)
+        if rc > 0 {
+            return (TerminationStatus(waitStatus: status), ResourceUsage(usage))
+        } else if rc == 0 {
+            return nil // Child still running
+        }
+        #elseif os(Linux) || os(Android)
         var siginfo = siginfo_t()
-        if waitid(idtype, id, &siginfo, flags) != -1 {
-            return siginfo
-        } else if errno != EINTR {
+        let rc = linux_waitid(P_PID, id_t(pid), &siginfo, WEXITED | WNOHANG, &usage)
+        if rc != -1 {
+            // If si_pid and si_signo are both 0, the child is still running since we used WNOHANG
+            if siginfo.si_pid == 0 && siginfo.si_signo == 0 {
+                return nil
+            }
+            return (TerminationStatus(siginfo), ResourceUsage(usage))
+        }
+        #endif
+        // rc == -1: either EINTR (retry) or a real error
+        if errno != EINTR {
             throw Errno(rawValue: errno)
         }
     }
@@ -722,6 +748,20 @@ internal extension TerminationStatus {
     }
 }
 
+#if os(macOS) || os(FreeBSD) || os(OpenBSD)
+internal extension TerminationStatus {
+    init(waitStatus: CInt) {
+        if _was_process_exited(waitStatus) != 0 {
+            self = .exited(CInt(_get_exit_code(waitStatus)))
+        } else if _was_process_signaled(waitStatus) != 0 {
+            self = .unhandledException(CInt(_get_signal_code(waitStatus)))
+        } else {
+            fatalError("Unexpected wait status: \(waitStatus)")
+        }
+    }
+}
+#endif
+
 #if os(OpenBSD) || os(Linux) || os(Android)
 internal extension siginfo_t {
     var si_status: Int32 {

Sources/Subprocess/Platforms/Subprocess+Windows.swift

@@ -605,7 +605,7 @@ extension PlatformOptions: CustomStringConvertible, CustomDebugStringConvertible
 @Sendable
 internal func monitorProcessTermination(
     for processIdentifier: ProcessIdentifier
-) async throws(SubprocessError) -> TerminationStatus {
+) async throws(SubprocessError) -> (TerminationStatus, ResourceUsage) {
     // Once the continuation resumes, it will need to unregister the wait, so
     // yield the wait handle back to the calling scope.
     var waitHandle: HANDLE?
@@ -650,17 +650,20 @@ internal func monitorProcessTermination(
         }
     }
 
+    // Collect resource usage while the process handle is still valid
+    let resourceUsage = ResourceUsage(processHandle: processIdentifier.processDescriptor)
+
     var status: DWORD = 0
     guard GetExitCodeProcess(processIdentifier.processDescriptor, &status) else {
         // The child process terminated but we couldn't get its status back.
         // Assume generic failure.
-        return .exited(1)
+        return (.exited(1), resourceUsage)
     }
     let exitCodeValue = CInt(bitPattern: .init(status))
     guard exitCodeValue >= 0 else {
-        return .unhandledException(status)
+        return (.unhandledException(status), resourceUsage)
     }
-    return .exited(status)
+    return (.exited(status), resourceUsage)
 }
 
 // MARK: - Subprocess Control