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

@@ -378,6 +378,7 @@ public func run<
     return ExecutionResult(
         processIdentifier: result.value.processIdentifier,
         terminationStatus: result.terminationStatus,
+        resourceUsage: result.resourceUsage,
         closureOutput: result.value.closureResult,
         standardOutput: result.value.output,
         standardError: result.value.error

Sources/Subprocess/Configuration.swift

@@ -162,14 +162,15 @@ public struct Configuration: Sendable {
             // stale entry and reject its registrations.
             AsyncIO.shared.cleanup(processIdentifier: processIdentifier)
 
-            let terminationStatus = try reapProcess(with: processIdentifier)
+            let (terminationStatus, resourceUsage) = try reapProcess(with: processIdentifier)
 
             if let monitorError {
                 throw monitorError
             }
 
             return try ExecutionOutcome(
                 terminationStatus: terminationStatus,
+                resourceUsage: resourceUsage,
                 value: result.get()
             )
         } onCleanup: {

Sources/Subprocess/Platforms/Subprocess+Unix.swift

@@ -694,14 +694,13 @@ extension PlatformOptions: CustomStringConvertible, CustomDebugStringConvertible
 @Sendable
 internal func reapProcess(
     with processIdentifier: ProcessIdentifier
-) throws(SubprocessError) -> TerminationStatus {
+) throws(SubprocessError) -> (TerminationStatus, ResourceUsage) {
     do throws(Errno) {
         // On some platforms, the process exit notification (in particular NOTE_EXIT from kqueue)
         // 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()
-        return status
+        return try processIdentifier.blockingReap()
     } catch {
         let subprocessError: SubprocessError = .failedToMonitor(withUnderlyingError: error)
         throw subprocessError
@@ -711,12 +710,12 @@ internal func reapProcess(
 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)
     }
 
@@ -730,18 +729,55 @@ extension ProcessIdentifier {
 }
 
 @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 _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)
+        }
+    }
 }
 
-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 _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()
+        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)
+        }
     }
-    return TerminationStatus(siginfo)
 }
 
 internal func _peekIfExited(pid: pid_t) throws(Errno) -> Bool {
@@ -775,6 +811,21 @@ internal extension TerminationStatus {
     }
 }
 
+#if os(macOS) || os(FreeBSD) || os(OpenBSD)
+internal extension TerminationStatus {
+    init(waitStatus: CInt) {
+        switch (_was_process_exited(waitStatus) != 0, _was_process_signaled(waitStatus) != 0) {
+        case (true, false):
+            self = .exited(CInt(_get_exit_code(waitStatus)))
+        case (false, true):
+            self = .signaled(CInt(_get_signal_code(waitStatus)))
+        case (true, true), (false, false):
+            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

@@ -575,18 +575,21 @@ internal func waitForProcessTermination(
 @Sendable
 internal func reapProcess(
     with processIdentifier: ProcessIdentifier
-) throws(SubprocessError) -> TerminationStatus {
+) throws(SubprocessError) -> (TerminationStatus, ResourceUsage) {
     // Windows keeps the exit code reachable through the process HANDLE
     // until the HANDLE is closed, so there is no zombie to reap. We just
     // need to read the exit code via `GetExitCodeProcess`.
+    // 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 {
         throw SubprocessError.failedToMonitor(
             withUnderlyingError: .init(rawValue: GetLastError())
         )
     }
 
-    return .exited(status)
+    return (.exited(status), resourceUsage)
 }
 
 // MARK: - Subprocess Control

Sources/Subprocess/Result.swift

@@ -15,6 +15,115 @@ import System
 import SystemPackage
 #endif
 
+#if canImport(Darwin)
+public import Darwin
+#elseif canImport(Glibc)
+public import Glibc
+#elseif canImport(Musl)
+public import Musl
+#elseif canImport(Android)
+public import Android
+#elseif canImport(WinSDK)
+import WinSDK
+#endif
+
+// MARK: - ResourceUsage
+
+/// Resource usage information for a terminated subprocess.
+public struct ResourceUsage: Sendable, Hashable {
+    /// The total amount of time spent executing in user mode.
+    public let userTime: Duration
+    /// The total amount of time spent executing in kernel mode.
+    public let systemTime: Duration
+    /// The peak resident set size (maximum memory used), in bytes.
+    public let maxRSS: Int
+
+    #if !os(Windows)
+    /// The underlying POSIX resource usage information.
+    public let rusage: rusage
+    #endif
+}
+
+extension ResourceUsage {
+    #if os(Windows)
+    internal init(processHandle: HANDLE) {
+        var creationTime = FILETIME()
+        var exitTime = FILETIME()
+        var kernelTime = FILETIME()
+        var userFileTime = FILETIME()
+
+        if GetProcessTimes(
+            processHandle,
+            &creationTime,
+            &exitTime,
+            &kernelTime,
+            &userFileTime
+        ) {
+            self.userTime = Duration(userFileTime)
+            self.systemTime = Duration(kernelTime)
+        } else {
+            self.userTime = .zero
+            self.systemTime = .zero
+        }
+
+        var memInfo = PROCESS_MEMORY_COUNTERS()
+        memInfo.cb = DWORD(MemoryLayout<PROCESS_MEMORY_COUNTERS>.size)
+        if K32GetProcessMemoryInfo(
+            processHandle,
+            &memInfo,
+            DWORD(MemoryLayout<PROCESS_MEMORY_COUNTERS>.size)
+        ) {
+            self.maxRSS = Int(memInfo.PeakWorkingSetSize)
+        } else {
+            self.maxRSS = 0
+        }
+    }
+    #else
+    internal init(_ usage: rusage) {
+        self.userTime = Duration(
+            secondsComponent: Int64(usage.ru_utime.tv_sec),
+            attosecondsComponent: Int64(usage.ru_utime.tv_usec) * 1_000_000_000_000
+        )
+        self.systemTime = Duration(
+            secondsComponent: Int64(usage.ru_stime.tv_sec),
+            attosecondsComponent: Int64(usage.ru_stime.tv_usec) * 1_000_000_000_000
+        )
+        #if canImport(Darwin)
+        self.maxRSS = Int(usage.ru_maxrss) // bytes on Darwin
+        #elseif os(Linux) || os(Android) || os(FreeBSD) || os(OpenBSD)
+        self.maxRSS = Int(usage.ru_maxrss) * 1024 // KiB to bytes (Linux, FreeBSD, OpenBSD, NetBSD)
+        #else
+        #error("ru_maxrss unit scaling not defined for this platform")
+        #endif
+        self.rusage = usage
+    }
+    #endif
+}
+
+#if os(Windows)
+extension Duration {
+    fileprivate init(_ ft: FILETIME) {
+        let hundredNanos = UInt64(ft.dwHighDateTime) << 32 | UInt64(ft.dwLowDateTime)
+        let seconds = Int64(hundredNanos / 10_000_000)
+        let remainder = Int64(hundredNanos % 10_000_000)
+        self = Duration(
+            secondsComponent: seconds,
+            attosecondsComponent: remainder * 100_000_000_000
+        )
+    }
+}
+#endif
+
+// MARK: - ExecutionSummary Protocol
+
+/// Protocol providing common properties for subprocess execution results.
+public protocol ExecutionSummary: Sendable {
+    /// The termination status of the child process.
+    var terminationStatus: TerminationStatus { get }
+    /// The resource usage of the terminated child process.
+    var resourceUsage: ResourceUsage { get }
+}
+
 // MARK: - Result
 
 /// The result of running a subprocess, including the closure's return value,
@@ -42,27 +151,54 @@ public struct ExecutionResult<
     public let standardOutput: Output.OutputType
     /// The collected standard error of the subprocess.
     public let standardError: Error.OutputType
+    /// The resource usage of the terminated child process.
+    public let resourceUsage: ResourceUsage
 
     /// The value returned by the body closure passed to `run`.
     public let closureOutput: ClosureResult
 
     internal init(
         processIdentifier: ProcessIdentifier,
         terminationStatus: TerminationStatus,
+        resourceUsage: ResourceUsage,
         closureOutput: ClosureResult,
         standardOutput: Output.OutputType,
         standardError: Error.OutputType
     ) {
         self.processIdentifier = processIdentifier
         self.terminationStatus = terminationStatus
+        self.resourceUsage = resourceUsage
         self.closureOutput = closureOutput
         self.standardOutput = standardOutput
         self.standardError = standardError
     }
 }
 
+// MARK: - rusage Conformances
+#if !os(Windows)
+extension rusage: @retroactive Equatable {
+    public static func == (lhs: rusage, rhs: rusage) -> Bool {
+        withUnsafeBytes(of: lhs) { lhsBytes in
+            withUnsafeBytes(of: rhs) { rhsBytes in
+                lhsBytes.elementsEqual(rhsBytes)
+            }
+        }
+    }
+}
+
+extension rusage: @retroactive Hashable {
+    public func hash(into hasher: inout Hasher) {
+        withUnsafeBytes(of: self) { bytes in
+            hasher.combine(bytes: bytes)
+        }
+    }
+}
+#endif
+
 // MARK: - ExecutionResult Conformances
 
+extension ExecutionResult: ExecutionSummary {}
+
 extension ExecutionResult: Equatable where Output.OutputType: Equatable, Error.OutputType: Equatable, ClosureResult: Equatable {}
 
 extension ExecutionResult: Hashable where Output.OutputType: Hashable, Error.OutputType: Hashable, ClosureResult: Hashable {}
@@ -74,6 +210,7 @@ extension ExecutionResult: CustomStringConvertible where Output.OutputType: Cust
             ExecutionResult(
                 processIdentifier: \(self.processIdentifier),
                 terminationStatus: \(self.terminationStatus.description),
+                resourceUsage: \(self.resourceUsage),
                 closureOutput: \(String(describing: self.closureOutput)),
                 standardOutput: \(self.standardOutput.description)
                 standardError: \(self.standardError.description)
@@ -90,6 +227,7 @@ where Output.OutputType: CustomDebugStringConvertible, Error.OutputType: CustomD
             ExecutionResult(
                 processIdentifier: \(self.processIdentifier),
                 terminationStatus: \(self.terminationStatus.debugDescription),
+                resourceUsage: \(self.resourceUsage),
                 closureOutput: \(String(describing: self.closureOutput)),
                 standardOutput: \(self.standardOutput.debugDescription)
                 standardError: \(self.standardError.debugDescription)
@@ -105,11 +243,14 @@ where Output.OutputType: CustomDebugStringConvertible, Error.OutputType: CustomD
 internal struct ExecutionOutcome<Result: Sendable>: Sendable {
     /// The termination status of the child process.
     internal let terminationStatus: TerminationStatus
+    /// The resource usage of the terminated child process.
+    internal let resourceUsage: ResourceUsage
     /// The value returned by the closure passed to the `run` method.
     internal let value: Result
 
-    internal init(terminationStatus: TerminationStatus, value: Result) {
+    internal init(terminationStatus: TerminationStatus, resourceUsage: ResourceUsage, value: Result) {
         self.terminationStatus = terminationStatus
+        self.resourceUsage = resourceUsage
         self.value = value
     }
 }
@@ -124,6 +265,7 @@ extension ExecutionOutcome: CustomStringConvertible where Result: CustomStringCo
         return """
             ExecutionOutcome(
                 terminationStatus: \(self.terminationStatus.description),
+                resourceUsage: \(self.resourceUsage),
                 value: \(self.value.description)
             )
             """
@@ -136,6 +278,7 @@ extension ExecutionOutcome: CustomDebugStringConvertible where Result: CustomDeb
         return """
             ExecutionOutcome(
                 terminationStatus: \(self.terminationStatus.debugDescription),
+                resourceUsage: \(self.resourceUsage),
                 value: \(self.value.debugDescription)
             )
             """