diff --git a/Proposals/0007-swift-subprocess.md b/Proposals/0007-swift-subprocess.md index 14bb38fa0..b130a0c1b 100644 --- a/Proposals/0007-swift-subprocess.md +++ b/Proposals/0007-swift-subprocess.md @@ -20,7 +20,7 @@ - Added a section describing `Task Cancellation` - Clarified for `readFrom()` and `writeTo()` Subprocess will close the passed in file descriptor right after spawning the process when `closeWhenDone` is set to true. - Adjusted argument orders in `Arguments`. - - Added `Subprocess.run(withConfiguration:...)` in favor or `Configuration.run()`. + - Added `run(withConfiguration:...)` in favor or `Configuration.run()`. - **v4**: Minor updates (primarily name changes): - Dropped the `executing` label from `.run()`. - Removed references to `Subprocess.AsyncBytes`: @@ -34,7 +34,7 @@ - Updated `StandardInputWriter` to be non-sendable. - Renamed `PlatformOptions.additionalAttributeConfigurator` to `Platform.preSpawnAttributeConfigurator`; renamed `PlatformOptions.additionalFileAttributeConfigurator` to `Platform.preSpawnFileAttributeConfigurator`. - Updated all `closeWhenDone` parameter labels to `closeAfterSpawningProcess`. - - Renamed `Subprocess.Result` to `Subprocess.ExecutionResult`. + - Renamed `Subprocess.Result` to `ExecutionResult`. - Added `Codable` support to `TerminationStatus` and `ExecutionResult`. - Renamed `TerminationStatus.exit`: - From `.exit` to `.exited`. @@ -75,10 +75,32 @@ - Teardown Sequence support (for Darwin and Linux): - Introduced `Subprocess.teardown(using:)` to allow developers to gracefully shutdown a subprocess. - Introuuced `PlatformOptions.teardownSequence` that will be used to gracefully shutdown the subprocess if the parent task is cancelled. +- **v6**: String support, minor changes around IO and closure `sending` requirements: + - Added a `Configuration` based overload for `runDetached`. + - Updated input types to support: `Sequence`, `Sequence` and `AsyncSequence` (dropped `AsyncSequence` in favor of `AsyncSequence`). + - Added `isolation` parameter for closure based `.run` methods. + - Dropped `sending` requirement for closure passed to `.run`. + - Windows: renamed `ProcessIdentifier.processID` to `ProcessIdentifier.value`. + - Updated `TeardownStep` to use `Duration` instead of raw nanoseconds. + - Switched all generic parameters to full words instead of a letter. + - Introduced String support: + - Added `some StringProtocol` input overloads for `run()`. + - Introduced `protocol Subprocess.OutputConvertible`, which allows developers to define their own type as the return type for `CollecedOutput.standard{Output|Error}`. + - Make `CollectedOutput`, its associated `run()` family of methods, and `CollectedOutputMethod` genric. The entire chain of genrics is ultimately inferred from `CollectedOutputMethod`, which allows developers to specify custom return type for `.standard{Output|Error}`. +- **v7**: Major redesign + - Instead of `Subprocess.OutputMethod` and `Subprocess.InputMethod`, now IOs are protocol based: `Subprocess.InputProtocol` and `Subprocess.OutputProtocol` with concrete implementations + - Remove all input overloads of `run()` since now we use concrete instances iof `InputProtocol` to represent them. + - Renamed package module name to `Subprocess`. + - Dropped the `struct Subprocess` namespace. Now all `run()`s are free standing functions + - `Executable`: + - Renamed `.named` to `.name`. + - Renamed `.at` to `.path`. + - Split `Subprocess` into two modules: `Subprocess` with no `Foundation` dependency and `SubprocessFoundation` with `Foundation` dependency + - Introduce `struct Buffer` ## Introduction -As Swift establishes itself as a general-purpose language for both compiled and scripting use cases, one persistent pain point for developers is process creation. The existing Foundation API for spawning a process, `NSTask`, originated in Objective-C. It was subsequently renamed to `Process` in Swift. As the language has continued to evolve, `Process` has not kept up. It lacks support for `async/await`, makes extensive use of completion handlers, and uses Objective-C exceptions to indicate developer error. This proposal introduces a new type called `Subprocess`, which addresses the ergonomic shortcomings of `Process` and enhances the experience of using Swift for scripting and other areas such as server-side development. +As Swift establishes itself as a general-purpose language for both compiled and scripting use cases, one persistent pain point for developers is process creation. The existing Foundation API for spawning a process, `NSTask`, originated in Objective-C. It was subsequently renamed to `Process` in Swift. As the language has continued to evolve, `Process` has not kept up. It lacks support for `async/await`, makes extensive use of completion handlers, and uses Objective-C exceptions to indicate developer error. This proposal introduces a new package called `Subprocess`, which addresses the ergonomic shortcomings of `Process` and enhances the experience of using Swift for scripting and other areas such as server-side development. ## Motivation @@ -145,253 +167,205 @@ While the Swift script above is functionally equivalent to the shell script, it ## Proposed solution -We propose a new type, `struct Subprocess`, that will eventually replace `Process` as the canonical way to launch a process in `Swift`. +We propose a new package, `Subprocess`, that will eventually replace `Process` as the canonical way to launch a process in `Swift`. -Here's the above script rewritten using `Subprocess`: +Here's the above script rewritten using `Subprocess` package: ```swift #!/usr/bin/swift -import FoundationEssentials +import Subprocess -let gitResult = try await Subprocess.run( // <- 0 - .named("git"), // <- 1 +let gitResult = try await run( // <- 0 + .name("git"), // <- 1 arguments: ["diff", "--name-only"] ) -var changedFiles = String( - data: gitResult.standardOutput, - encoding: .utf8 -)! +let changedFiles = gitResult.standardOutput! if changedFiles.isEmpty { changedFiles = "No changed files" } -_ = try await Subprocess.run( - .named("say"), +_ = try await run( + .name("say"), arguments: [changedFiles] ) ``` Let's break down the example above: -0. `Subprocess` is constructed entirely on the `async/await` paradigm. The `run()` method utilizes `await` to allow the child process to finish, asynchronously returning an `ExecutionResult`. Additionally, there is an closure based overload of `run()` that offers more granulated control, which will be discussed later. +0. `Subprocess` is constructed entirely on the `async/await` paradigm. The `run()` method utilizes `await` to allow the child process to finish, asynchronously returning an `CollectedResult`. Additionally, there is an closure based overload of `run()` that offers more granulated control, which will be discussed later. 1. There are two primary ways to configure the executable being run: - - The default approach, recommended for most developers, is `.at(FilePath)`. This allows developers to specify a full path to an executable. - - Alternatively, developers can use `.named(String)` to instruct `Subprocess` to look up the executable path based on heuristics such as the `$PATH` environment variable. + - The default approach, recommended for most developers, is `.path(FilePath)`. This allows developers to specify a full path to an executable. + - Alternatively, developers can use `.name(String)` to instruct `Subprocess` to look up the executable path based on heuristics such as the `$PATH` environment variable. ## Detailed Design -### The New `Subprocess` Type +The latest API documentation can be viewed by running the following command: -We propose a new `struct Subprocess`. Developers primarily interact with `Subprocess` via the static `run` methods which asynchronously executes a subprocess. +``` +swift package --disable-sandbox preview-documentation --target Subprocess +``` -```swift -@available(FoundationPreview 0.4, *) -@available(iOS, unavailable) -@available(tvOS, unavailable) -@available(watchOS, unavailable) -extension Subprocess { - /// Run a executable with given parameters and capture its - /// standard output and standard error. - /// - Parameters: - /// - executable: The executable to run. - /// - arguments: The arguments to pass to the executable. - /// - environment: The environment to use for the process. - /// - workingDirectory: The working directory to use for the subprocess. - /// - platformOptions: The platform specific options to use - /// when running the executable. - /// - input: The input to send to the executable. - /// - output: The method to use for collecting the standard output. - /// - error: The method to use for collecting the standard error. - /// - Returns: `CollectedResult` which contains process identifier, - /// termination status, captured standard output and standard error. - public static func run( - _ executable: Executable, - arguments: Arguments = [], - environment: Environment = .inherit, - workingDirectory: FilePath? = nil, - platformOptions: PlatformOptions = .default, - input: InputMethod = .noInput, - output: CollectedOutputMethod = .collect(), - error: CollectedOutputMethod = .collect() - ) async throws -> CollectedResult - - /// Run a executable with given parameters and capture its - /// standard output and standard error. - /// - Parameters: - /// - executable: The executable to run. - /// - arguments: The arguments to pass to the executable. - /// - environment: The environment to use for the process. - /// - workingDirectory: The working directory to use for the subprocess. - /// - platformOptions: The platform specific options to use - /// when running the executable. - /// - input: The input to send to the executable. - /// - output: The method to use for collecting the standard output. - /// - error: The method to use for collecting the standard error. - /// - Returns: `CollectedResult` which contains process identifier, - /// termination status, captured standard output and standard error. - public static func run( - _ executable: Executable, - arguments: Arguments = [], - environment: Environment = .inherit, - workingDirectory: FilePath? = nil, - platformOptions: PlatformOptions = .default, - input: some Sequence, - output: CollectedOutputMethod = .collect(), - error: CollectedOutputMethod = .collect() - ) async throws -> CollectedResult - - /// Run a executable with given parameters and capture its - /// standard output and standard error. - /// - Parameters: - /// - executable: The executable to run. - /// - arguments: The arguments to pass to the executable. - /// - environment: The environment to use for the process. - /// - workingDirectory: The working directory to use for the subprocess. - /// - platformOptions: The platform specific options to use - /// when running the executable. - /// - input: The input to send to the executable. - /// - output: The method to use for collecting the standard output. - /// - error: The method to use for collecting the standard error. - /// - Returns: `CollectedResult` which contains process identifier, - /// termination status, captured standard output and standard error. - public static func run( - _ executable: Executable, - arguments: Arguments = [], - environment: Environment = .inherit, - workingDirectory: FilePath? = nil, - platformOptions: PlatformOptions = .default, - input: S, - output: CollectedOutputMethod = .collect(), - error: CollectedOutputMethod = .collect() - ) async throws -> CollectedResult where S.Element == UInt8 -} +### `Subprocess` and `SubprocessFoundation` Modules -// MARK: - Custom Execution Body -extension Subprocess { - /// Run a executable with given parameters and a custom closure - /// to manage the running subprocess' lifetime and its IOs. - /// - Parameters: - /// - executable: The executable to run. - /// - arguments: The arguments to pass to the executable. - /// - environment: The environment in which to run the executable. - /// - workingDirectory: The working directory in which to run the executable. - /// - platformOptions: The platform specific options to use - /// when running the executable. - /// - input: The input to send to the executable. - /// - output: The method to use for redirecting the standard output. - /// - error: The method to use for redirecting the standard error. - /// - body: The custom execution body to manually control the running process - /// - Returns a `ExecutableResult` type containing the return value - /// of the closure. - public static func run( - _ executable: Executable, - arguments: Arguments = [], - environment: Environment = .inherit, - workingDirectory: FilePath? = nil, - platformOptions: PlatformOptions = .default, - input: InputMethod = .noInput, - output: RedirectedOutputMethod = .redirectToSequence, - error: RedirectedOutputMethod = .redirectToSequence, - _ body: (sending @escaping (Subprocess) async throws -> R) - ) async throws -> ExecutionResult - - /// Run a executable with given parameters and a custom closure - /// to manage the running subprocess' lifetime and its IOs. - /// - Parameters: - /// - executable: The executable to run. - /// - arguments: The arguments to pass to the executable. - /// - environment: The environment in which to run the executable. - /// - workingDirectory: The working directory in which to run the executable. - /// - platformOptions: The platform specific options to use - /// when running the executable. - /// - input: The input to send to the executable. - /// - output: The method to use for redirecting the standard output. - /// - error: The method to use for redirecting the standard error. - /// - body: The custom execution body to manually control the running process - /// - Returns a `ExecutableResult` type containing the return value - /// of the closure. - public static func run( - _ executable: Executable, - arguments: Arguments = [], - environment: Environment = .inherit, - platformOptions: PlatformOptions = .default, - input: some Sequence, - output: RedirectedOutputMethod = .redirectToSequence, - error: RedirectedOutputMethod = .redirectToSequence, - _ body: (sending @escaping (Subprocess) async throws -> R) - ) async throws -> ExecutionResult - - /// Run a executable with given parameters and a custom closure - /// to manage the running subprocess' lifetime and its IOs. - /// - Parameters: - /// - executable: The executable to run. - /// - arguments: The arguments to pass to the executable. - /// - environment: The environment in which to run the executable. - /// - workingDirectory: The working directory in which to run the executable. - /// - platformOptions: The platform specific options to use - /// when running the executable. - /// - input: The input to send to the executable. - /// - output: The method to use for redirecting the standard output. - /// - error: The method to use for redirecting the standard error. - /// - body: The custom execution body to manually control the running process - /// - Returns a `ExecutableResult` type containing the return value - /// of the closure. - public static func run( - _ executable: Executable, - arguments: Arguments = [], - environment: Environment = .inherit, - workingDirectory: FilePath? = nil, - platformOptions: PlatformOptions = .default, - input: S, - output: RedirectedOutputMethod = .redirectToSequence, - error: RedirectedOutputMethod = .redirectToSequence, - _ body: (sending @escaping (Subprocess) async throws -> R) - ) async throws -> ExecutionResult where S.Element == UInt8 - - /// Run a executable with given parameters and a custom closure - /// to manage the running subprocess' lifetime and write to its - /// standard input via `StandardInputWriter` - /// - Parameters: - /// - executable: The executable to run. - /// - arguments: The arguments to pass to the executable. - /// - environment: The environment in which to run the executable. - /// - workingDirectory: The working directory in which to run the executable. - /// - platformOptions: The platform specific options to use - /// when running the executable. - /// - output: The method to use for redirecting the standard output. - /// - error: The method to use for redirecting the standard error. - /// - body: The custom execution body to manually control the running process - /// - Returns the custom result type returned by the closure - public static func run( - _ executable: Executable, - arguments: Arguments = [], - environment: Environment = .inherit, - workingDirectory: FilePath? = nil, - platformOptions: PlatformOptions = .default, - output: RedirectedOutputMethod = .redirectToSequence, - error: RedirectedOutputMethod = .redirectToSequence, - _ body: (sending @escaping (Subprocess, StandardInputWriter) async throws -> R) - ) async throws -> ExecutionResult - - /// Run a executable with given parameters specified by a - /// `Subprocess.Configuration` - /// - Parameters: - /// - configuration: The `Subprocess` configuration to run. - /// - output: The method to use for redirecting the standard output. - /// - error: The method to use for redirecting the standard error. - /// - body: The custom configuration body to manually control - /// the running process and write to its standard input. - /// - Returns a ExecutableResult type containing the return value - /// of the closure. - public static func run( - _ configuration: Configuration, - output: RedirectedOutputMethod = .redirectToSequence, - error: RedirectedOutputMethod = .redirectToSequence, - _ body: (sending @escaping (Subprocess, StandardInputWriter) async throws -> R) - ) async throws -> ExecutionResult -} +Within this package, we propose two modules: `Subprocess` and `SubprocessFoundation`. `Subprocess` serves as the “core” module, relying solely on `swift-system` and the standard library. `SubprocessFoundation` extends `Subprocess` by depending on and incorporating types from `Foundation`. + + +### The `run()` Family of Methods + +We propose several `run()` functions that allow developers to asynchronously execute a subprocess. + +```swift +/// Run a executable with given parameters and a custom closure +/// to manage the running subprocess' lifetime and its IOs. +/// - Parameters: +/// - executable: The executable to run. +/// - arguments: The arguments to pass to the executable. +/// - environment: The environment in which to run the executable. +/// - workingDirectory: The working directory in which to run the executable. +/// - platformOptions: The platform specific options to use +/// when running the executable. +/// - input: The input to send to the executable. +/// - output: The method to use for redirecting the standard output. +/// - error: The method to use for redirecting the standard error. +/// - body: The custom execution body to manually control the running process +/// - Returns a CollectedResult containing the result of the run. +@available(macOS 9999, *) // Span availability +public func run< + Input: InputProtocol, + Output: OutputProtocol, + Error: OutputProtocol +>( + _ executable: Executable, + arguments: Arguments = [], + environment: Environment = .inherit, + workingDirectory: FilePath? = nil, + platformOptions: PlatformOptions = PlatformOptions(), + input: Input = .none, + output: Output = .string, + error: Error = .discarded +) async throws -> CollectedResult + +/// Run a executable with given parameters and a custom closure +/// to manage the running subprocess' lifetime and its IOs. +/// - Parameters: +/// - executable: The executable to run. +/// - arguments: The arguments to pass to the executable. +/// - environment: The environment in which to run the executable. +/// - workingDirectory: The working directory in which to run the executable. +/// - platformOptions: The platform specific options to use +/// when running the executable. +/// - input: span to write to subprocess' standard input. +/// - output: The method to use for redirecting the standard output. +/// - error: The method to use for redirecting the standard error. +/// - body: The custom execution body to manually control the running process +/// - Returns a CollectedResult containing the result of the run. +@available(macOS 9999, *) // Span availability +public func run< + InputElement: BitwiseCopyable, + Output: OutputProtocol, + Error: OutputProtocol +>( + _ executable: Executable, + arguments: Arguments = [], + environment: Environment = .inherit, + workingDirectory: FilePath? = nil, + platformOptions: PlatformOptions = PlatformOptions(), + input: borrowing Span, + output: Output = .string, + error: Error = .discarded +) async throws -> CollectedResult + +/// Run a executable with given parameters and a custom closure +/// to manage the running subprocess' lifetime and its IOs. +/// - Parameters: +/// - executable: The executable to run. +/// - arguments: The arguments to pass to the executable. +/// - environment: The environment in which to run the executable. +/// - workingDirectory: The working directory in which to run the executable. +/// - platformOptions: The platform specific options to use +/// when running the executable. +/// - input: The input to send to the executable. +/// - output: How to manage the executable standard ouput. +/// - error: How to manager executable standard error. +/// - body: The custom execution body to manually control the running process +/// - Returns a ExecutableResult type containing the return value +/// of the closure. +public func run( + _ executable: Executable, + arguments: Arguments = [], + environment: Environment = .inherit, + workingDirectory: FilePath? = nil, + platformOptions: PlatformOptions = PlatformOptions(), + input: Input = .none, + output: Output, + error: Error, + isolation: isolated (any Actor)? = #isolation, + body: (@escaping (Execution) async throws -> Result) +) async throws -> ExecutionResult where Output.OutputType == Void, Error.OutputType == Void + + +/// Run a executable with given parameters and a custom closure +/// to manage the running subprocess' lifetime and write to its +/// standard input via `StandardInputWriter` +/// - Parameters: +/// - executable: The executable to run. +/// - arguments: The arguments to pass to the executable. +/// - environment: The environment in which to run the executable. +/// - workingDirectory: The working directory in which to run the executable. +/// - platformOptions: The platform specific options to use +/// when running the executable. +/// - output:How to handle executable's standard output +/// - error: How to handle executable's standard error +/// - body: The custom execution body to manually control the running process +/// - Returns a ExecutableResult type containing the return value +/// of the closure. +public func run( + _ executable: Executable, + arguments: Arguments = [], + environment: Environment = .inherit, + workingDirectory: FilePath? = nil, + platformOptions: PlatformOptions = PlatformOptions(), + output: Output, + error: Error, + isolation: isolated (any Actor)? = #isolation, + body: (@escaping (Execution, StandardInputWriter) async throws -> Result) +) async throws -> ExecutionResult where Output.OutputType == Void, Error.OutputType == Void + +/// Run a executable with given parameters and a custom closure +/// to manage the running subprocess' lifetime and its IOs. +/// - Parameters: +/// - configuration: The `Subprocess` configuration to run. +/// - input: The input to send to the executable. +/// - output: The method to use for redirecting the standard output. +/// - error: The method to use for redirecting the standard error. +/// - Returns a CollectedResult containing the result of the run. +@available(macOS 9999, *) +public func run< + Input: InputProtocol, + Output: OutputProtocol, + Error: OutputProtocol +>( + _ configuration: Configuration, + input: Input = .none, + output: Output = .string, + error: Error = .discarded +) async throws -> CollectedResult + +/// Run a executable with given parameters specified by a `Configuration`, +/// redirect its standard output to sequence and discard its standard error. +/// - Parameters: +/// - configuration: The `Subprocess` configuration to run. +/// - body: The custom configuration body to manually control +/// the running process and write to its standard input. +/// - Returns a ExecutableResult type containing the return value +/// of the closure. +public func run( + _ configuration: Configuration, + isolation: isolated (any Actor)? = #isolation, + body: (@escaping (Execution, StandardInputWriter) async throws -> Result) +) async throws -> ExecutionResult ``` The `run` methods can generally be divided into two categories, each addressing distinctive use cases of `Subprocess`: @@ -399,40 +373,36 @@ The `run` methods can generally be divided into two categories, each addressing ```swift // Simple ls with no standard input -let ls = try await Subprocess.run( - .named("ls"), - output: .collect -) -print("Items in current directory: \(String(data: ls.standardOutput, encoding: .utf8)!)") +let ls = try await run(.name("ls")) +print("Items in current directory: \(ls.standardOutput!)") // Launch VSCode with arguments -let code = try await Subprocess.run( - .named("code"), +let code = try await run( + .name("code"), arguments: ["/some/directory"] ) -print("Code launched successfully: \(result.terminationStatus.isSuccess)") +print("Code launched successfully: \(code.terminationStatus.isSuccess)") // Launch `cat` with sequence written to standardInput -let inputData = "Hello SwiftFoundation".utf8CString.map { UInt8($0) } -let cat = try await Subprocess.run( - .named("cat"), - input: inputData, - output: .collect +let inputData = Array("Hello SwiftFoundation".utf8) +let cat = try await run( + .name("cat"), + input: .array(inputData), + output: .string ) -print("Cat result: \(String(data: cat.standardOutput, encoding: .utf8)!)") +print("Cat result: \(cat.standardOutput!)") ``` -- Alternatively, developers can leverage the closure-based approach. These methods spawn the child process and invoke the provided `body` closure with a `Subprocess` object. Developers can send signals to the running subprocess or transform `standardOutput` or `standardError` to the desired result type within the closure. One additional variation of the closure-based methods provides the `body` closure with an additional `Subprocess.StandardInputWriter` object, allowing developers to write to the standard input of the subprocess directly. These methods asynchronously wait for the child process to exit before returning the result. +- Alternatively, developers can leverage the closure-based approach. These methods spawn the child process and invoke the provided `body` closure with an `Execution` object. Developers can send signals to the running subprocess or transform `standardOutput` or `standardError` to the desired result type within the closure. One additional variation of the closure-based methods provides the `body` closure with an additional `StandardInputWriter` object, allowing developers to write to the standard input of the subprocess directly. These methods asynchronously wait for the child process to exit before returning the result. ```swift // Use curl to call REST API struct MyType: Codable { ... } -let result = try await Subprocess.run( - .named("curl"), - arguments: ["/some/rest/api"], - output: .redirect +let result = try await run( + .name("curl"), + arguments: ["/some/rest/api"] ) { var buffer = Data() for try await chunk in $0.standardOutput { @@ -444,9 +414,8 @@ let result = try await Subprocess.run( print("Result: \(result)") // Perform custom write and write the standard output -let result = try await Subprocess.run( - .at("/some/executable"), - output: .redirect +let result = try await run( + .path("/some/executable") ) { subprocess, writer in try await writer.write("Hello World".utf8CString) try await writer.finish() @@ -454,229 +423,218 @@ let result = try await Subprocess.run( } ``` -Both styles of the `run` methods provide convenient overloads that allow developers to pass a `Sequence` or `AsyncSequence` to the standard input of the subprocess. +#### Unmanaged Subprocess -The `Subprocess` object itself is designed to represent an executed process. This execution could be either in progress or completed. Direct construction of `Subprocess` instances is not supported; instead, a `Subprocess` object is passed to the `body` closure of `run()`. This object is only valid within the scope of the closure, and developers may use it to send signals to the child process or retrieve the child's standard I/Os via `AsyncSequence`s. +In addition to the managed `run` family of methods, `Subprocess` also supports an unmanaged `runDetached` method that simply spawns the executable and returns its process identifier without awaiting for it to complete. This mode is particularly useful in scripting scenarios where the subprocess being launched requires outlasting the parent process. This setup is essential for programs that function as “trampolines” (e.g., JVM Launcher) to spawn other processes. + +Since `Subprocess` is unable to monitor the state of the subprocess or capture and clean up input/output, it requires explicit `FileDescriptor` to bind to the subprocess’ IOs. Developers are responsible for managing the creation and lifetime of the provided file descriptor; if no file descriptor is specified, `Subprocess` binds its standard IOs to `/dev/null`. ```swift -/// An object that represents a subprocess of the current process. +/// Run a executable with given parameters and return its process +/// identifier immediately without monitoring the state of the +/// subprocess nor waiting until it exits. /// -/// Using `Subprocess`, your program can run another program as a subprocess -/// and can monitor that program’s execution. A `Subprocess` object creates a -/// **separate executable** entity; it’s different from `Thread` because it doesn’t -/// share memory space with the process that creates it. -@available(FoundationPreview 0.4, *) -@available(iOS, unavailable) -@available(tvOS, unavailable) -@available(watchOS, unavailable) -public struct Subprocess: Sendable { - /// The process identifier of the current subprocess +/// This method is useful for launching subprocesses that outlive their +/// parents (for example, daemons and trampolines). +/// +/// - Parameters: +/// - executable: The executable to run. +/// - arguments: The arguments to pass to the executable. +/// - environment: The environment to use for the process. +/// - workingDirectory: The working directory for the process. +/// - platformOptions: The platform specific options to use for the process. +/// - input: A file descriptor to bind to the subprocess' standard input. +/// - output: A file descriptor to bind to the subprocess' standard output. +/// - error: A file descriptor to bind to the subprocess' standard error. +/// - Returns: the process identifier for the subprocess. +public func runDetached( + _ executable: Executable, + arguments: Arguments = [], + environment: Environment = .inherit, + workingDirectory: FilePath? = nil, + platformOptions: PlatformOptions = PlatformOptions(), + input: FileDescriptor? = nil, + output: FileDescriptor? = nil, + error: FileDescriptor? = nil +) throws -> ProcessIdentifier + +/// Run a executable with given configuration and return its process +/// identifier immediately without monitoring the state of the +/// subprocess nor waiting until it exits. +/// +/// This method is useful for launching subprocesses that outlive their +/// parents (for example, daemons and trampolines). +/// +/// - Parameters: +/// - configuration: The `Subprocess` configuration to run. +/// - input: A file descriptor to bind to the subprocess' standard input. +/// - output: A file descriptor to bind to the subprocess' standard output. +/// - error: A file descriptor to bind to the subprocess' standard error. +/// - Returns: the process identifier for the subprocess. +public func runDetached( + _ configuration: Configuration, + input: FileDescriptor? = nil, + output: FileDescriptor? = nil, + error: FileDescriptor? = nil +) throws -> ProcessIdentifier +``` + + +### `Execution` + +In contrast to the monolithic `Process`, `Subprocess` utilizes two types to model the lifetime of a process. `Configuration` (discussed later) and `Execution`. `Execution` is designed to represent an executed process. This execution could be either in progress or completed. Direct construction of `Execution` instances is not supported; instead, a `Execution` object is passed to the `body` closure of `run()`. This object is only valid within the scope of the closure, and developers may use it to send signals to the child process or retrieve the child's standard I/Os via `AsyncSequence`s. + +```swift +/// An object that represents a subprocess that has been +/// executed. You can use this object to send signals to the +/// child process as well as stream its output and error. +public struct Execution< + Output: OutputProtocol, + Error: OutputProtocol +>: Sendable { + /// The process identifier of the current execution public let processIdentifier: ProcessIdentifier +} + +extension Execution where Output == SequenceOutput { /// The standard output of the subprocess. - /// Accessing this property will **fatalError** if: - /// - `.output` was NOT set to `.redirectToSequence` when the subprocess was spawned; + /// Accessing this property will **fatalError** if + /// - `.output` wasn't set to `.redirectToSequence` when the subprocess was spawned; /// - This property was accessed multiple times. Subprocess communicates with - /// parent process via pipe under the hood and each pipe can only be consumed ones. - public var standardOutput: some AsyncSequence { get } + /// parent process via pipe under the hood and each pipe can only be consumed once. + public var standardOutput: some AsyncSequence +} + +extension Execution where Error == SequenceOutput { /// The standard error of the subprocess. /// Accessing this property will **fatalError** if - /// - `.error` was NOT set to `.redirectToSequence` when the subprocess was spawned; + /// - `.error` wasn't set to `.redirectToSequence` when the subprocess was spawned; /// - This property was accessed multiple times. Subprocess communicates with - /// parent process via pipe under the hood and each pipe can only be consumed ones. - public var standardError: some AsyncSequence { get } + /// parent process via pipe under the hood and each pipe can only be consumed once. + public var standardError: some AsyncSequence } -#if canImport(Glibc) || canImport(Darwin) -extension Subprocess { - @available(FoundationPreview 0.4, *) - @available(iOS, unavailable) - @available(tvOS, unavailable) - @available(watchOS, unavailable) - /// A platform independent identifier for a subprocess. - public struct ProcessIdentifier: Sendable, Hashable, Codable { - /// The platform specific process identifier value - public let value: pid_t - - public init(value: pid_t) - } +#if canImport(WinSDK) +/// A platform independent identifier for a subprocess. +public struct ProcessIdentifier: Sendable, Hashable, Codable { + /// Windows specifc process identifier value + public let value: DWORD + /// Windows specific thread identifier associated with process + public let threadID: DWORD } -#elseif canImport(WinSDK) -extension Subprocess { - /// A platform independent identifier for a subprocess. - @available(FoundationPreview 0.4, *) - @available(iOS, unavailable) - @available(tvOS, unavailable) - @available(watchOS, unavailable) - public struct ProcessIdentifier: Sendable, Hashable, Codable { - /// Windows specifc process identifier value - public let processID: DWORD - /// Windows specific thread identifier associated with process - public let threadID: DWORD - - public init(processID: DWORD, threadID: DWORD) - } +#else +/// A platform independent identifier for a Subprocess. +public struct ProcessIdentifier: Sendable, Hashable, Codable { + /// The platform specific process identifier value + public let value: pid_t } -#endif // canImport(WinSDK) - -extension Subprocess.ProcessIdentifier : CustomStringConvertible, CustomDebugStringConvertible {} -``` - -#### Unmanaged Subprocess - -In addition to the managed `run` family of methods, `Subprocess` also supports an unmanaged `runDetached` method that simply spawns the executable and returns its process identifier without awaiting for it to complete. This mode is particularly useful in scripting scenarios where the subprocess being launched requires outlasting the parent process. This setup is essential for programs that function as “trampolines” (e.g., JVM Launcher) to spawn other processes. - -Since `Subprocess` is unable to monitor the state of the subprocess or capture and clean up input/output, it requires explicit `FileDescriptor` to bind to the subprocess’ IOs. Developers are responsible for managing the creation and lifetime of the provided file descriptor; if no file descriptor is specified, `Subprocess` binds its standard IOs to `/dev/null`. +#endif -```swift -@available(FoundationPreview 0.4, *) -@available(iOS, unavailable) -@available(tvOS, unavailable) -@available(watchOS, unavailable) -extension Subprocess { - /// Run a executable with given parameters and return its process - /// identifier immediately without monitoring the state of the - /// subprocess nor waiting until it exits. - /// - /// This method is useful for launching subprocesses that outlive their - /// parents (for example, daemons and trampolines). - /// - /// - Parameters: - /// - executable: The executable to run. - /// - arguments: The arguments to pass to the executable. - /// - environment: The environment to use for the process. - /// - workingDirectory: The working directory for the process. - /// - platformOptions: The platform specific options to use for the process. - /// - input: A file descriptor to bind to the subprocess' standard input. - /// - output: A file descriptor to bind to the subprocess' standard output. - /// - error: A file descriptor to bind to the subprocess' standard error. - /// - Returns: the process identifier for the subprocess. - public static func runDetached( - _ executable: Executable, - arguments: Arguments = [], - environment: Environment = .inherit, - workingDirectory: FilePath? = nil, - platformOptions: PlatformOptions = .default, - input: FileDescriptor? = nil, - output: FileDescriptor? = nil, - error: FileDescriptor? = nil - ) throws -> ProcessIdentifier -} ``` -### Signals (macOS and Linux) +#### Signals (macOS and Linux) -`Subprocess` uses `struct Subprocess.Signal` to represent the signal that could be sent via `send()` on Unix systems (macOS and Linux). Developers could either initialize `Signal` directly using the raw signal value or use one of the common values defined as static property. +`Subprocess` uses `struct Signal` to represent the signal that could be sent via `send()` on Unix systems (macOS and Linux). Developers could either initialize `Signal` directly using the raw signal value or use one of the common values defined as static property. ```swift #if canImport(Glibc) || canImport(Darwin) -extension Subprocess { - /// Signals are standardized messages sent to a running program - /// to trigger specific behavior, such as quitting or error handling. - @available(FoundationPreview 0.4, *) - @available(iOS, unavailable) - @available(tvOS, unavailable) - @available(watchOS, unavailable) - public struct Signal : Hashable, Sendable { - /// The underlying platform specific value for the signal - public let rawValue: Int32 - - /// The `.interrupt` signal is sent to a process by its - /// controlling terminal when a user wishes to interrupt - /// the process. - public static var interrupt: Self { get } - /// The `.terminate` signal is sent to a process to request its - /// termination. Unlike the `.kill` signal, it can be caught - /// and interpreted or ignored by the process. This allows - /// the process to perform nice termination releasing resources - /// and saving state if appropriate. `.interrupt` is nearly - /// identical to `.terminate`. - public static var terminate: Self { get } - /// The `.suspend` signal instructs the operating system - /// to stop a process for later resumption. - public static var suspend: Self { get } - /// The `resume` signal instructs the operating system to - /// continue (restart) a process previously paused by the - /// `.suspend` signal. - public static var resume: Self { get } - /// The `.kill` signal is sent to a process to cause it to - /// terminate immediately (kill). In contrast to `.terminate` - /// and `.interrupt`, this signal cannot be caught or ignored, - /// and the receiving process cannot perform any - /// clean-up upon receiving this signal. - public static var kill: Self { get } - /// The `.terminalClosed` signal is sent to a process when - /// its controlling terminal is closed. In modern systems, - /// this signal usually means that the controlling pseudo - /// or virtual terminal has been closed. - public static var terminalClosed: Self { get } - /// The `.quit` signal is sent to a process by its controlling - /// terminal when the user requests that the process quit - /// and perform a core dump. - public static var quit: Self { get } - /// The `.userDefinedOne` signal is sent to a process to indicate - /// user-defined conditions. - public static var userDefinedOne: Self { get } - /// The `.userDefinedTwo` signal is sent to a process to indicate - /// user-defined conditions. - public static var userDefinedTwo: Self { get } - /// The `.alarm` signal is sent to a process when the corresponding - /// time limit is reached. - public static var alarm: Self { get } - /// The `.windowSizeChange` signal is sent to a process when - /// its controlling terminal changes its size (a window change). - public static var windowSizeChange: Self { get } - - public init(rawValue: Int32) - } +/// Signals are standardized messages sent to a running program +/// to trigger specific behavior, such as quitting or error handling. +public struct Signal : Hashable, Sendable { + /// The underlying platform specific value for the signal + public let rawValue: Int32 + + /// The `.interrupt` signal is sent to a process by its + /// controlling terminal when a user wishes to interrupt + /// the process. + public static var interrupt: Self { get } + /// The `.terminate` signal is sent to a process to request its + /// termination. Unlike the `.kill` signal, it can be caught + /// and interpreted or ignored by the process. This allows + /// the process to perform nice termination releasing resources + /// and saving state if appropriate. `.interrupt` is nearly + /// identical to `.terminate`. + public static var terminate: Self { get } + /// The `.suspend` signal instructs the operating system + /// to stop a process for later resumption. + public static var suspend: Self { get } + /// The `resume` signal instructs the operating system to + /// continue (restart) a process previously paused by the + /// `.suspend` signal. + public static var resume: Self { get } + /// The `.kill` signal is sent to a process to cause it to + /// terminate immediately (kill). In contrast to `.terminate` + /// and `.interrupt`, this signal cannot be caught or ignored, + /// and the receiving process cannot perform any + /// clean-up upon receiving this signal. + public static var kill: Self { get } + /// The `.terminalClosed` signal is sent to a process when + /// its controlling terminal is closed. In modern systems, + /// this signal usually means that the controlling pseudo + /// or virtual terminal has been closed. + public static var terminalClosed: Self { get } + /// The `.quit` signal is sent to a process by its controlling + /// terminal when the user requests that the process quit + /// and perform a core dump. + public static var quit: Self { get } + /// The `.userDefinedOne` signal is sent to a process to indicate + /// user-defined conditions. + public static var userDefinedOne: Self { get } + /// The `.userDefinedTwo` signal is sent to a process to indicate + /// user-defined conditions. + public static var userDefinedTwo: Self { get } + /// The `.alarm` signal is sent to a process when the corresponding + /// time limit is reached. + public static var alarm: Self { get } + /// The `.windowSizeChange` signal is sent to a process when + /// its controlling terminal changes its size (a window change). + public static var windowSizeChange: Self { get } + + public init(rawValue: Int32) +} + +extension Execution { /// Send the given signal to the child process. /// - Parameters: /// - signal: The signal to send. /// - shouldSendToProcessGroup: Whether this signal should be sent to /// the entire process group. - @available(FoundationPreview 0.4, *) - @available(iOS, unavailable) - @available(tvOS, unavailable) - @available(watchOS, unavailable) - public func send(_ signal: Signal, toProcessGroup shouldSendToProcessGroup: Bool) throws + public func send( + signal: Signal, + toProcessGroup shouldSendToProcessGroup: Bool = false + ) throws } + #endif // canImport(Glibc) || canImport(Darwin) ``` -### Teardown Sequence (macOS and Linux) +#### Teardown Sequence (macOS and Linux) `Subprocess` provides a graceful shutdown mechanism for child processes using the `.teardown(using:)` method. This method allows for a sequence of teardown steps to be executed, with the final step always sending a `.kill` signal. ```swift #if canImport(Glibc) || canImport(Darwin) -extension Subprocses { +/// A step in the graceful shutdown teardown sequence. +/// It consists of a signal to send to the child process and the +/// duration allowed for the child process to exit before proceeding +/// to the next step. +public struct TeardownStep: Sendable, Hashable { + /// Sends `signal` to the process and allows `allowedDurationToExit` + /// for the process to exit before proceeding to the next step. + /// The final step in the sequence will always send a `.kill` signal. + public static func sendSignal( + _ signal: Signal, + allowedDurationToExit: Duration + ) -> Self +} + +extension Execution { /// Performs a sequence of teardown steps on the Subprocess. /// Teardown sequence always ends with a `.kill` signal /// - Parameter sequence: The steps to perform. - @available(FoundationPreview 0.4, *) - @available(iOS, unavailable) - @available(tvOS, unavailable) - @available(watchOS, unavailable) public func teardown(using sequence: [TeardownStep]) async - - /// A step in the graceful shutdown teardown sequence. - /// It consists of a signal to send to the child process and the - /// number of nanoseconds allowed for the child process to exit - /// before proceeding to the next step. - @available(FoundationPreview 0.4, *) - @available(iOS, unavailable) - @available(tvOS, unavailable) - @available(watchOS, unavailable) - public struct TeardownStep: Sendable, Hashable { - /// Sends `signal` to the process and provides `allowedNanoSecondsToExit` - /// nanoseconds for the process to exit before proceeding to the next step. - /// The final step in the sequence will always send a `.kill` signal. - public static func sendSignal( - _ signal: Signal, - allowedNanoSecondsToExit: UInt64 - ) -> Self - } } #endif // canImport(Glibc) || canImport(Darwin) ``` @@ -684,30 +642,26 @@ extension Subprocses { A teardown sequence is a series of signals sent to the child process, accompanied by a specified time limit for the child process to terminate before proceeding to the next step. For instance, it may be appropriate to initially send `.quit` and `.terminate` signals to the child process to facilitate a graceful shutdown before sending `.kill`. ```swift -let result = try await Subprocess.run( - .at("/bin/bash"), +let result = try await run( + .path("/bin/bash"), arguments: [...] -) { subprocess in +) { execution in // ... more work - await subprocess.teardown(using: [ - .sendSignal(.quit, allowedNanoSecondsToExit: 100_000_000), - .sendSignal(.terminate, allowedNanoSecondsToExit: 100_000_000), + await execution.teardown(using: [ + .sendSignal(.quit, allowedDurationToExit: .milliseconds(100)), + .sendSignal(.terminate, allowedDurationToExit: .milliseconds(100)), ]) } ``` -### Process Controls (Windows) +#### Process Controls (Windows) -Windows does not have a centralized signaling system similar to Unix. Instead, it provides direct methods to suspend, resume, and terminate the subprocess: +The Windows does not have a centralized signaling system similar to Unix. Instead, it provides direct methods to suspend, resume, and terminate the subprocess: ```swift #if canImport(WinSDK) -@available(FoundationPreview 0.4, *) -@available(iOS, unavailable) -@available(tvOS, unavailable) -@available(watchOS, unavailable) -extension Subprocess { +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 @@ -720,155 +674,154 @@ extension Subprocess { ``` -### `Subprocess.StandardInputWriter` - -`StandardInputWriter` provides developers with direct control over writing to the child process's standard input. Similar to the `Subprocess` object itself, developers should use the `StandardInputWriter` object passed to the `body` closure, and this object is only valid within the body of the closure. +### `Configuration` -**Note**: Developers should call `finish()` when they have completed writing to signal that the standard input file descriptor should be closed. +`Configuration` represents the collection of information needed to spawn a process. This type is designed to be very similar to the existing `Process`, enabling you to configure your process in a manner akin to `NSTask`: ```swift -extension Subprocess { - /// A writer that writes to the standard input of the subprocess. - @available(FoundationPreview 0.4, *) - @available(iOS, unavailable) - @available(tvOS, unavailable) - @available(watchOS, unavailable) - public struct StandardInputWriter { - /// Write a sequence of UInt8 to the standard input of the subprocess. - /// - Parameter sequence: The sequence of bytes to write. - public func write(_ sequence: S) async throws where S : Sequence, S.Element == UInt8 - /// Write a sequence of CChar to the standard input of the subprocess. - /// - Parameter sequence: The sequence of bytes to write. - public func write(_ sequence: S) async throws where S : Sequence, S.Element == CChar - - /// Write a AsyncSequence of CChar to the standard input of the subprocess. - /// - Parameter sequence: The sequence of bytes to write. - public func write(_ asyncSequence: S) async throws where S.Element == CChar - /// Write a AsyncSequence of UInt8 to the standard input of the subprocess. - /// - Parameter sequence: The sequence of bytes to write. - public func write(_ asyncSequence: S) async throws where S.Element == UInt8 - /// Signal all writes are finished - public func finish() async throws - } +/// A collection of configurations parameters to use when +/// spawning a subprocess. +public struct Configuration : Sendable, Hashable { + /// The executable to run. + public var executable: Executable + /// The arguments to pass to the executable. + public var arguments: Arguments + /// The environment to use when running the executable. + public var environment: Environment + /// The working directory to use when running the executable. + public var workingDirectory: FilePath + /// The platform specifc options to use when + /// running the subprocess. + public var platformOptions: PlatformOptions + + public init( + executing executable: Executable, + arguments: Arguments = [], + environment: Environment = .inherit, + workingDirectory: FilePath? = nil, + platformOptions: PlatformOptions = .default + ) } -@available(macOS, unavailable) -@available(iOS, unavailable) -@available(tvOS, unavailable) -@available(watchOS, unavailable) -@available(*, unavailable) -extension Subprocess.StandardInputWriter : Sendable {} +extension Configuration : CustomStringConvertible, CustomDebugStringConvertible {} ``` +**Note:** the `.workingDirectory` property defaults to the current working directory of the calling process. + -### `Subprocess.Configuration` +### `StandardInputWriter` -In contrast to the monolithic `Process`, `Subprocess` utilizes various types to model the lifetime of a process. `Subprocess.Configuration` represents the collection of information needed to spawn a process. This type is designed to be very similar to the existing `Process`, enabling you to configure your process in a manner akin to `NSTask`: +`StandardInputWriter` provides developers with direct control over writing to the child process's standard input. Similar to the `Execution` object, developers should use the `StandardInputWriter` object passed to the `body` closure, and this object is only valid within the body of the closure. + +**Note**: Developers should call `finish()` when they have completed writing to signal that the standard input file descriptor should be closed. + +In the core `Subprocess` module, `StandardInputWriter` offers overrides of `write()` methods for writing `String`s and `UInt8` arrays: ```swift -public extension Subprocess { - /// A collection of configurations parameters to use when - /// spawning a subprocess. - @available(FoundationPreview 0.4, *) - @available(iOS, unavailable) - @available(tvOS, unavailable) - @available(watchOS, unavailable) - public struct Configuration : Sendable, Hashable { - /// The executable to run. - public var executable: Executable - /// The arguments to pass to the executable. - public var arguments: Arguments - /// The environment to use when running the executable. - public var environment: Environment - /// The working directory to use when running the executable. - public var workingDirectory: FilePath - /// The platform specifc options to use when - /// running the subprocess. - public var platformOptions: PlatformOptions - - public init( - executing executable: Executable, - arguments: Arguments = [], - environment: Environment = .inherit, - workingDirectory: FilePath? = nil, - platformOptions: PlatformOptions = .default - ) - } +/// A writer that writes to the standard input of the subprocess. +public final actor StandardInputWriter { + /// Write an array of UInt8 to the standard input of the subprocess. + /// - Parameter array: The sequence of bytes to write. + /// - Returns number of bytes written. + public func write( + _ array: [UInt8] + ) async throws -> Int + + /// Write a StringProtocol to the standard input of the subprocess. + /// - Parameters: + /// - string: The string to write. + /// - encoding: The encoding to use when converting string to bytes + /// - Returns number of bytes written. + public func write( + _ string: some StringProtocol, + using encoding: Encoding.Type = UTF8.self + ) async throws -> Int + + /// Signal all writes are finished + public func finish() async throws } - -extension Subprocess.Configuration : CustomStringConvertible, CustomDebugStringConvertible {} ``` -**Note:** +`SubprocessFoundation` extends `StandardInputWriter` to work with `Data`: -- The `.workingDirectory` property defaults to the current working directory of the calling process. +```swift +import Foundation -Beyond the configurable parameters exposed by these static run methods, `Subprocess.Configuration` also provides **platform-specific** launch options via `PlatformOptions`. +extension StandardInputWriter { + /// Write a `Data` to the standard input of the subprocess. + /// - Parameter data: The sequence of bytes to write. + /// - Returns number of bytes written. + public func write( + _ data: Data + ) async throws -> Int + + /// Write a AsyncSequence of Data to the standard input of the subprocess. + /// - Parameter sequence: The sequence of bytes to write. + /// - Returns number of bytes written. + public func write( + _ asyncSequence: AsyncSendableSequence + ) async throws -> Int where AsyncSendableSequence.Element == Data +} +``` -### `Subprocess.PlatformOptions` on Darwin +### `PlatformOptions` on Darwin -For Darwin, we propose the following `PlatformOptions`: +Beyond the configurable parameters exposed by these static run methods, `Configuration` also provides **platform-specific** launch options via `PlatformOptions`. For Darwin, we propose the following `PlatformOptions`: ```swift #if canImport(Darwin) -extension Subprocess { - /// The collection of platform-specific settings - /// to configure the subprocess when running - @available(FoundationPreview 0.4, *) - @available(iOS, unavailable) - @available(tvOS, unavailable) - @available(watchOS, unavailable) - public struct PlatformOptions: Sendable, Hashable { - public var qualityOfService: QualityOfService - // Set user ID for the subprocess - public var userID: uid_t? - /// Set the real and effective group ID and the saved - /// set-group-ID of the subprocess, equivalent to calling - /// `setgid()` on the child process. - /// Group ID is used to control permissions, particularly - /// for file access. - public var groupID: gid_t? - // Set list of supplementary group IDs for the subprocess - public var supplementaryGroups: [gid_t]? - /// Set the process group for the subprocess, equivalent to - /// calling `setpgid()` on the child process. - /// Process group ID is used to group related processes for - /// controlling signals. - public var processGroupID: pid_t? = nil - // Creates a session and sets the process group ID - // i.e. Detach from the terminal. - public var createSession: Bool - public var launchRequirementData: Data? - /// An ordered list of steps in order to tear down the child - /// process in case the parent task is cancelled before - /// the child proces terminates. - /// Always ends in sending a `.kill` signal at the end. - public var teardownSequence: [TeardownStep] - /// A closure to configure platform-specific - /// spawning constructs. This closure enables direct - /// configuration or override of underlying platform-specific - /// spawn settings that `Subprocess` utilizes internally, - /// in cases where Subprocess does not provide higher-level - /// APIs for such modifications. - /// - /// On Darwin, Subprocess uses `posix_spawn()` as the - /// underlying spawning mechanism. This closure allows - /// modification of the `posix_spawnattr_t` spawn attribute - /// and file actions `posix_spawn_file_actions_t` before - /// they are sent to `posix_spawn()`. - public var preSpawnProcessConfigurator: ( - @Sendable ( - inout posix_spawnattr_t?, - inout posix_spawn_file_actions_t? - ) throws -> Void - )? = nil - - public init() {} - } +/// The collection of platform-specific settings +/// to configure the subprocess when running +public struct PlatformOptions: Sendable, Hashable { + public var qualityOfService: QualityOfService + // Set user ID for the subprocess + public var userID: uid_t? + /// Set the real and effective group ID and the saved + /// set-group-ID of the subprocess, equivalent to calling + /// `setgid()` on the child process. + /// Group ID is used to control permissions, particularly + /// for file access. + public var groupID: gid_t? + // Set list of supplementary group IDs for the subprocess + public var supplementaryGroups: [gid_t]? + /// Set the process group for the subprocess, equivalent to + /// calling `setpgid()` on the child process. + /// Process group ID is used to group related processes for + /// controlling signals. + public var processGroupID: pid_t? = nil + // Creates a session and sets the process group ID + // i.e. Detach from the terminal. + public var createSession: Bool + public var launchRequirementData: Data? + /// An ordered list of steps in order to tear down the child + /// process in case the parent task is cancelled before + /// the child proces terminates. + /// Always ends in sending a `.kill` signal at the end. + public var teardownSequence: [TeardownStep] + /// A closure to configure platform-specific + /// spawning constructs. This closure enables direct + /// configuration or override of underlying platform-specific + /// spawn settings that `Subprocess` utilizes internally, + /// in cases where Subprocess does not provide higher-level + /// APIs for such modifications. + /// + /// On Darwin, Subprocess uses `posix_spawn()` as the + /// underlying spawning mechanism. This closure allows + /// modification of the `posix_spawnattr_t` spawn attribute + /// and file actions `posix_spawn_file_actions_t` before + /// they are sent to `posix_spawn()`. + public var preSpawnProcessConfigurator: ( + @Sendable ( + inout posix_spawnattr_t?, + inout posix_spawn_file_actions_t? + ) throws -> Void + )? = nil + + public init() {} } -extension Subprocess.PlatformOptions : CustomStringConvertible, CustomDebugStringConvertible {} +extension PlatformOptions : CustomStringConvertible, CustomDebugStringConvertible {} #endif // canImport(Darwin) ``` @@ -877,7 +830,7 @@ extension Subprocess.PlatformOptions : CustomStringConvertible, CustomDebugStrin For Darwin, we propose a closure `.preSpawnProcessConfigurator: (@Sendable (inout posix_spawnattr_t?, inout posix_spawn_file_actions_t?) throws -> Void` which provides developers with an opportunity to configure `posix_spawnattr_t` and `posix_spawn_file_actions_t` just before they are passed to `posix_spawn()`. For instance, developers can set additional spawn flags: ```swift -var platformOptions: Subprocess.PlatformOptions = .default +var platformOptions = PlatformOptions() platformOptions.preSpawnProcessConfigurator = { spawnAttr, _ in let flags: Int32 = POSIX_SPAWN_CLOEXEC_DEFAULT | POSIX_SPAWN_SETSIGMASK | @@ -890,7 +843,7 @@ platformOptions.preSpawnProcessConfigurator = { spawnAttr, _ in Similarly, a developer might want to bind child file descriptors, other than standard input (fd 0), standard output (fd 1), and standard error (fd 2), to parent file descriptors: ```swift -var platformOptions: Subprocess.PlatformOptions = .default +var platformOptions = PlatformOptions() // Bind child fd 4 to a parent fd platformOptions.preSpawnProcessConfigurator = { _, fileAttr in let parentFd: FileDescriptor = … @@ -899,77 +852,71 @@ platformOptions.preSpawnProcessConfigurator = { _, fileAttr in ``` -### `Subprocess.PlatformOptions` on Linux +### `PlatformOptions` on Linux For Linux, we propose a similar `PlatformOptions` configuration: ```swift #if canImport(Glibc) -extension Subprocess { - /// The collection of Linux specific configurations - @available(FoundationPreview 0.4, *) - @available(iOS, unavailable) - @available(tvOS, unavailable) - @available(watchOS, unavailable) - public struct PlatformOptions: Sendable, Hashable { - // Set user ID for the subprocess - public var userID: uid_t? - /// Set the real and effective group ID and the saved - /// set-group-ID of the subprocess, equivalent to calling - /// `setgid()` on the child process. - /// Group ID is used to control permissions, particularly - /// for file access. - public var groupID: gid_t? - // Set list of supplementary group IDs for the subprocess - public var supplementaryGroups: [gid_t]? - /// Set the process group for the subprocess, equivalent to - /// calling `setpgid()` on the child process. - /// Process group ID is used to group related processes for - /// controlling signals. - public var processGroupID: pid_t? - // Creates a session and sets the process group ID - // i.e. Detach from the terminal. - public var createSession: Bool - // Whether the subprocess should close all file - // descriptors except for the ones explicitly passed - // as `input`, `output`, or `error` when `run` is executed - // This is equivelent to setting `POSIX_SPAWN_CLOEXEC_DEFAULT` - // on Darwin. This property is default to be `false` - // because `POSIX_SPAWN_CLOEXEC_DEFAULT` is a darwin-specific - // extension and we can only emulate it on Linux. - public var closeAllUnknownFileDescriptors: Bool - /// An ordered list of steps in order to tear down the child - /// process in case the parent task is cancelled before - /// the child proces terminates. - /// Always ends in sending a `.kill` signal at the end. - public var teardownSequence: [TeardownStep] = [] - /// A closure to configure platform-specific - /// spawning constructs. This closure enables direct - /// configuration or override of underlying platform-specific - /// spawn settings that `Subprocess` utilizes internally, - /// in cases where Subprocess does not provide higher-level - /// APIs for such modifications. - /// - /// On Linux, Subprocess uses `fork/exec` as the - /// underlying spawning mechanism. This closure is called - /// after `fork()` but before `exec()`. You may use it to - /// call any necessary process setup functions. - public var preSpawnProcessConfigurator: ( - @convention(c) @Sendable () -> Void - )? = nil - - public init() {} - } +/// The collection of Linux specific configurations +public struct PlatformOptions: Sendable, Hashable { + // Set user ID for the subprocess + public var userID: uid_t? + /// Set the real and effective group ID and the saved + /// set-group-ID of the subprocess, equivalent to calling + /// `setgid()` on the child process. + /// Group ID is used to control permissions, particularly + /// for file access. + public var groupID: gid_t? + // Set list of supplementary group IDs for the subprocess + public var supplementaryGroups: [gid_t]? + /// Set the process group for the subprocess, equivalent to + /// calling `setpgid()` on the child process. + /// Process group ID is used to group related processes for + /// controlling signals. + public var processGroupID: pid_t? + // Creates a session and sets the process group ID + // i.e. Detach from the terminal. + public var createSession: Bool + // Whether the subprocess should close all file + // descriptors except for the ones explicitly passed + // as `input`, `output`, or `error` when `run` is executed + // This is equivelent to setting `POSIX_SPAWN_CLOEXEC_DEFAULT` + // on Darwin. This property is default to be `false` + // because `POSIX_SPAWN_CLOEXEC_DEFAULT` is a darwin-specific + // extension and we can only emulate it on Linux. + public var closeAllUnknownFileDescriptors: Bool + /// An ordered list of steps in order to tear down the child + /// process in case the parent task is cancelled before + /// the child proces terminates. + /// Always ends in sending a `.kill` signal at the end. + public var teardownSequence: [TeardownStep] = [] + /// A closure to configure platform-specific + /// spawning constructs. This closure enables direct + /// configuration or override of underlying platform-specific + /// spawn settings that `Subprocess` utilizes internally, + /// in cases where Subprocess does not provide higher-level + /// APIs for such modifications. + /// + /// On Linux, Subprocess uses `fork/exec` as the + /// underlying spawning mechanism. This closure is called + /// after `fork()` but before `exec()`. You may use it to + /// call any necessary process setup functions. + public var preSpawnProcessConfigurator: ( + @convention(c) @Sendable () -> Void + )? = nil + + public init() {} } -extension Subprocess.PlatformOptions : CustomStringConvertible, CustomDebugStringConvertible {} +extension PlatformOptions : CustomStringConvertible, CustomDebugStringConvertible {} #endif // canImport(Glibc) ``` Similar to the Darwin version, the Linux `PlatformOptions` also has an "escape hatch" closure that allows the developers to explicitly configure the subprocess. This closure is run after `fork` but before `exec`. In the example below, `preSpawnProcessConfigurator` can be used to set the group ID for the subprocess: ```swift -var platformOptions: Subprocess.PlatformOptions = .default +var platformOptions: PlatformOptions = .default // Set Group ID for process platformOptions.preSpawnProcessConfigurator = { setgid(4321) @@ -977,105 +924,99 @@ platformOptions.preSpawnProcessConfigurator = { ``` -### `Subprocess.PlatformOptions` on Windows +### `PlatformOptions` on Windows On Windows, we propose the following `PlatformOptions`: ```swift #if canImport(WinSDK) -extension Subprocess { - /// The collection of platform-specific settings - /// to configure the subprocess when running - @available(FoundationPreview 0.4, *) - @available(iOS, unavailable) - @available(tvOS, unavailable) - @available(watchOS, unavailable) - public struct PlatformOptions: Sendable, Hashable { - public struct UserCredentials: Sendable, Hashable { - // The name of the user. This is the name - // of the user account to run as. - public var username: String - // The clear-text password for the account. - public var password: String - // The name of the domain or server whose account database - // contains the account. - public var domain: String? - } - - /// `ConsoleBehavior` defines how should the console appear - /// when spawning a new process - public struct ConsoleBehavior: Sendable, Hashable { - /// The subprocess has a new console, instead of - /// inheriting its parent's console (the default). - public static let createNew: Self - /// For console processes, the new process does not - /// inherit its parent's console (the default). - /// The new process can call the `AllocConsole` - /// function at a later time to create a console. - public static let detatch: Self - /// The subprocess inherits its parent's console. - public static let inherit: Self - } +/// The collection of platform-specific settings +/// to configure the subprocess when running +public struct PlatformOptions: Sendable, Hashable { + public struct UserCredentials: Sendable, Hashable { + // The name of the user. This is the name + // of the user account to run as. + public var username: String + // The clear-text password for the account. + public var password: String + // The name of the domain or server whose account database + // contains the account. + public var domain: String? + } - /// `ConsoleBehavior` defines how should the window appear - /// when spawning a new process - public struct WindowStyle: Sendable, Hashable { - /// Activates and displays a window of normal size - public static let normal: Self - /// Does not activate a new window - public static let hidden: Self - /// Activates the window and displays it as a maximized window. - public static let maximized: Self - /// Activates the window and displays it as a minimized window. - public static let minimized: Self - } + /// `ConsoleBehavior` defines how should the console appear + /// when spawning a new process + public struct ConsoleBehavior: Sendable, Hashable { + /// The subprocess has a new console, instead of + /// inheriting its parent's console (the default). + public static let createNew: Self + /// For console processes, the new process does not + /// inherit its parent's console (the default). + /// The new process can call the `AllocConsole` + /// function at a later time to create a console. + public static let detatch: Self + /// The subprocess inherits its parent's console. + public static let inherit: Self + } - /// Sets user info when starting the process. If this - /// property is set, the Subprocess will be run - /// as the provided user - public var userCredentials: UserCredentials? = nil - /// The console behavior of the new process, - /// default to inheriting the console from parent process - public var consoleBehavior: ConsoleBehavior = .inherit - /// Window style to use when the process is started - public var windowStyle: WindowStyle = .normal - /// Whether to create a new process group for the new - /// process. The process group includes all processes - /// that are descendants of this root process. - /// The process identifier of the new process group - /// is the same as the process identifier. - public var createProcessGroup: Bool = false - /// A closure to configure platform-specific - /// spawning constructs. This closure enables direct - /// configuration or override of underlying platform-specific - /// spawn settings that `Subprocess` utilizes internally, - /// in cases where Subprocess does not provide higher-level - /// APIs for such modifications. - /// - /// On Windows, Subprocess uses `CreateProcessW()` as the - /// underlying spawning mechanism. This closure allows - /// modification of the `dwCreationFlags` creation flag - /// and startup info `STARTUPINFOW` before - /// they are sent to `CreateProcessW()`. - public var preSpawnProcessConfigurator: ( - @Sendable ( - inout DWORD, - inout STARTUPINFOW - ) throws -> Void - )? = nil - - public init() {} + /// `ConsoleBehavior` defines how should the window appear + /// when spawning a new process + public struct WindowStyle: Sendable, Hashable { + /// Activates and displays a window of normal size + public static let normal: Self + /// Does not activate a new window + public static let hidden: Self + /// Activates the window and displays it as a maximized window. + public static let maximized: Self + /// Activates the window and displays it as a minimized window. + public static let minimized: Self } + + /// Sets user info when starting the process. If this + /// property is set, the Subprocess will be run + /// as the provided user + public var userCredentials: UserCredentials? = nil + /// The console behavior of the new process, + /// default to inheriting the console from parent process + public var consoleBehavior: ConsoleBehavior = .inherit + /// Window style to use when the process is started + public var windowStyle: WindowStyle = .normal + /// Whether to create a new process group for the new + /// process. The process group includes all processes + /// that are descendants of this root process. + /// The process identifier of the new process group + /// is the same as the process identifier. + public var createProcessGroup: Bool = false + /// A closure to configure platform-specific + /// spawning constructs. This closure enables direct + /// configuration or override of underlying platform-specific + /// spawn settings that `Subprocess` utilizes internally, + /// in cases where Subprocess does not provide higher-level + /// APIs for such modifications. + /// + /// On Windows, Subprocess uses `CreateProcessW()` as the + /// underlying spawning mechanism. This closure allows + /// modification of the `dwCreationFlags` creation flag + /// and startup info `STARTUPINFOW` before + /// they are sent to `CreateProcessW()`. + public var preSpawnProcessConfigurator: ( + @Sendable ( + inout DWORD, + inout STARTUPINFOW + ) throws -> Void + )? = nil + + public init() {} } -extension Subprocess.PlatformOptions : CustomStringConvertible, CustomDebugStringConvertible {} +extension PlatformOptions : CustomStringConvertible, CustomDebugStringConvertible {} #endif // canImport(WinSDK) ``` Windows `PlatformOptions` uses `preSpawnProcessConfigurator` as the "escape hatch". Developers could use this closure to configure `dwCreationFlags` and `lpStartupInfo` that are used by the platform `CreateProcessW` to spawn the process: ```swift -var platformOptions: Subprocess.PlatformOptions = .default +var platformOptions: PlatformOptions = .default // Set Group ID for process platformOptions.preSpawnProcessConfigurator = { flag, startupInfo in // Set CREATE_NEW_CONSOLE for flag @@ -1091,302 +1032,543 @@ platformOptions.preSpawnProcessConfigurator = { flag, startupInfo in _(For more information on these values, checkout Microsoft's documentation [here](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw))_ -### `Subprocess.InputMethod` +### `InputProtocol` + +`InputProtocol` defines a set of methods that a type must implement to serve as the input source for a subprocess. In most cases, developers should utilize the concrete input types provided by `Subprocess`. However, developers have the option to create their own input types by conforming to `ManagedInputProtocol` and implementing the `write(into:)` method. + +The core `Subprocess` module is distributed with the following concrete input types: + +- `NoInput`: indicates there is no input sent to the subprocess. +- `FileDescriptorInput`: reads input from a specified `FileDescriptor` provided by the developer. Subprocess will automatically close the file descriptor after the process is spawned if `closeAfterSpawningProcess` is set to `true`. Note: when `closeAfterSpawningProcess` is `false`, the caller is responsible for closing the file descriptor even if `Subprocess` fails to spawn. +- `StringInput`: reads input from a given type conforming to `StringProtocol`. +- `ArrayInput`: reads input from a given array of `UInt8`. +- `CustomWriteInput`indicates that the Subprocess should read its input from `StandardInputWriter`. -In addition to supporting the direct passing of `Sequence` and `AsyncSequence` as the standard input to the child process, `Subprocess` also provides a `Subprocess.InputMethod` type that includes two additional input options: -- `.noInput`: Specifies that the subprocess does not require any standard input. This is the default value. -- `.readFrom`: Specifies that the subprocess should read its standard input from a file descriptor provided by the developer. Subprocess will automatically close the file descriptor after the process is spawned if `closeAfterSpawningProcess` is set to `true`. ```swift -extension Subprocess { - /// `InputMethod` defines how should the standard input - /// of the subprocess receive inputs. - @available(FoundationPreview 0.4, *) - @available(iOS, unavailable) - @available(tvOS, unavailable) - @available(watchOS, unavailable) - public struct InputMethod: Sendable, Hashable { - /// Subprocess should read no input. This option is equivalent - /// to bind the stanard input to `/dev/null`. - public static var noInput: Self - /// Subprocess should read input from a given file descriptor. - /// - Parameters: - /// - fd: the file descriptor to read from - /// - closeAfterSpawningProcess: whether the file descriptor - /// should be automatically closed after subprocess is spawned. - public static func readFrom(_ fd: FileDescriptor, closeAfterSpawningProcess: Bool) -> Self - } +/// `InputProtocol` specifies the set of methods that a type +/// must implement to serve as the input source for a subprocess. +/// Instead of developing custom implementations of `InputProtocol`, +/// it is recommended to utilize the default implementations provided +/// by the `Subprocess` library to specify the input handling requirements. +public protocol InputProtocol: Sendable { + /// Lazily create and return the FileDescriptor for reading + func readFileDescriptor() throws -> FileDescriptor? + /// Lazily create and return the FileDescriptor for writing + func writeFileDescriptor() throws -> FileDescriptor? + + /// Close the FileDescriptor for reading + func closeReadFileDescriptor() throws + /// Close the FileDescriptor for writing + func closeWriteFileDescriptor() throws + + /// Asynchronously write the input to the subprocess using the + /// write file descriptor + func write(into writeFileDescriptor: FileDescriptor) async throws +} + +/// `ManagedInputProtocol` is managed by `Subprocess` and +/// utilizes its `Pipe` type to facilitate input writing. +/// Developers have the option to implement custom +/// input types by conforming to `ManagedInputProtocol` +/// and implementing the `write(into:)` method. +public protocol ManagedInputProtocol: InputProtocol { + /// The underlying pipe used by this input in order to + /// write input to child process + var pipe: Pipe { get } +} + +/// A concrete `Input` type for subprocesses that indicates +/// the absence of input to the subprocess. On Unix-like systems, +/// `NoInput` redirects the standard input of the subprocess +/// to `/dev/null`, while on Windows, it does not bind any +/// file handle to the subprocess standard input handle. +public final class NoInput: InputProtocol { } + +/// A concrete `Input` type for subprocesses that +/// reads input from a specified `FileDescriptor`. +/// Developers have the option to instruct the `Subprocess` to +/// automatically close the provided `FileDescriptor` +/// after the subprocess is spawned. +public final class FileDescriptorInput: InputProtocol { } + +/// A concrete `Input` type for subprocesses that reads input +/// from a given type conforming to `StringProtocol`. +/// Developers can specify the string encoding to use when +/// encoding the string to data, which defaults to UTF-8. +public final class StringInput< + InputString: StringProtocol & Sendable, + Encoding: Unicode.Encoding +>: ManagedInputProtocol { } + +/// A concrete `Input` type for subprocesses that reads input +/// from a given `UInt8` Array. +public final class ArrayInput: ManagedInputProtocol { } + +/// A concrete `Input` type for subprocess that indicates that +/// the Subprocess should read its input from `StandardInputWriter`. +public struct CustomWriteInput: ManagedInputProtocol { } + +extension InputProtocol where Self == NoInput { + /// Create a Subprocess input that specfies there is no input + public static var none: Self { get } +} + +extension InputProtocol where Self == FileDescriptorInput { + /// Create a Subprocess input from a `FileDescriptor` and + /// specify whether the `FileDescriptor` should be closed + /// after the process is spawned. + public static func fileDescriptor( + _ fd: FileDescriptor, + closeAfterSpawningProcess: Bool + ) -> Self +} + +extension InputProtocol { + /// Create a Subprocess input from a `Array` of `UInt8`. + public static func array( + _ array: [UInt8] + ) -> Self where Self == ArrayInput + + /// Create a Subprocess input from a type that conforms to `StringProtocol` + public static func string< + InputString: StringProtocol & Sendable + >( + _ string: InputString + ) -> Self where Self == StringInput + + /// Create a Subprocess input from a type that conforms to `StringProtocol` + public static func string< + InputString: StringProtocol & Sendable, + Encoding: Unicode.Encoding & Sendable + >( + _ string: InputString, + using encoding: Encoding.Type + ) -> Self where Self == StringInput +} +``` + +`SubprocessFoundation` adds the following concrete input types that work with `Data`: + +- `DataInput`: reads input from a given `Data`. +- `DataSequenceInput`: reads input from a given sequence of `Data`. +- `DataAsyncSequenceInput`: reads input from a given async sequence of `Data`. + +```swift +import Foundation + +/// A concrete `Input` type for subprocesses that reads input +/// from a given `Data`. +public final class DataInput: ManagedInputProtocol { } + +/// A concrete `Input` type for subprocesses that accepts input +/// from a specified sequence of `Data`. This type should be preferred +/// over `Subprocess.UInt8SequenceInput` when dealing with +/// large amount input data. +public struct DataSequenceInput< + InputSequence: Sequence & Sendable +>: ManagedInputProtocol where InputSequence.Element == Data { } + +/// A concrete `Input` type for subprocesses that reads input +/// from a given async sequence of `Data`. +public struct DataAsyncSequenceInput< + InputSequence: AsyncSequence & Sendable +>: ManagedInputProtocol where InputSequence.Element == Data { } + + +extension InputProtocol { + /// Create a Subprocess input from a `Data` + public static func data(_ data: Data) -> Self where Self == DataInput + + /// Create a Subprocess input from a `Sequence` of `Data`. + public static func sequence( + _ sequence: InputSequence + ) -> Self where Self == DataSequenceInput + + /// Create a Subprocess input from a `AsyncSequence` of `Data`. + public static func sequence( + _ asyncSequence: InputSequence + ) -> Self where Self == DataAsyncSequenceInput } ``` Here are some examples: ```swift -// By default `InputMethod` is set to `.noInput` -let ls = try await Subprocess.run(.named("ls")) +// By default `InputMethod` is set to `.none` +let ls = try await run(.name("ls")) // Alternatively, developers could pass in a file descriptor let fd: FileDescriptor = ... -let cat = try await Subprocess.run(.named("cat"), input: .readFrom(fd, closeAfterSpawningProcess: true)) +let cat = try await run( + .name("cat"), + input: .fileDescriptor( + fd, + closeAfterSpawningProcess: true + ) +) // Pass in a async sequence directly -let sequence: AsyncSequence = ... -let exe = try await Subprocess.run(.at("/some/executable"), input: sequence) +let sequence: AsyncSequence = ... +let exe = try await run(.path("/some/executable"), input: .sequence(sequence)) ``` -### `Subprocess` Output Methods +### `OutputProtocol` + -`Subprocess` uses two types to describe where the standard output and standard error of the child process should be redirected. These two types, `Subprocess.CollectOutputMethod` and `Subprocess.RedirectOutputMethod`, correspond to the two general categories of `run` methods mentioned above. Similar to `InputMethod`, both `OutputMethod`s add two general output destinations: -- `.discard`: Specifies that the child process's output should be discarded, effectively written to `/dev/null`. -- `.writeTo`: Specifies that the child process should write its output to a file descriptor provided by the developer. Subprocess will automatically close the file descriptor after the process is spawned if `closeAfterSpawningProcess` is set to `true`. +`OutputProtocol` defines the set of methods that a type must implement to serve as the output target for a subprocess. Similarly to `InputProtocol`, developers should utilize the built-in concrete `Output` types provided with `Subprocess` whenever feasible; alternatively, they can create a type that conforms to `ManagedOutputProtocol` and implements `func output(from:) throws -> OutputType` for custom outputs. + +The core `Subprocess` module comes with the following concrete output types: + +- `DiscardedOutput`: indicates that the `Subprocess` should not collect or redirect output from the child process. +- `FileDescriptorOutput`: writes output to a specified `FileDescriptor`. Developers have the option to instruct the `Subprocess` to automatically close the provided `FileDescriptor` after the subprocess is spawned. +- `StringOutput`: collects output from the subprocess as `String` with the given encoding. +- `BytesOutput`: collects output from subprocess as `[UInt8]`. +- `SequenceOutput`: redirects the child output to the `.standardOutput` or `.standardError` property of `Execution`. This output type is only applicable to the `run()` family that takes a custom closure. -`CollectedOutMethod` adds one more option to non-closure-based `run` methods that return a `CollectedResult`: `.collect(upTo:)`. This option specifies that `Subprocess` should collect the output as `Data`. Since the output of a child process could be arbitrarily large, `Subprocess` imposes a limit on how many bytes it will collect. By default, this limit is 128kb. ```swift -extension Subprocess { - /// `CollectedOutputMethod` defines how should Subprocess collect - /// output from child process' standard output and standard error - @available(FoundationPreview 0.4, *) - @available(iOS, unavailable) - @available(tvOS, unavailable) - @available(watchOS, unavailable) - public struct CollectedOutputMethod: Sendable, Hashable { - /// Subprocess shold dicard the child process output. - /// This option is equivalent to binding the child process - /// output to `/dev/null`. - public static var discard: Self - /// Subprocess should collect the child process output - /// as `Data` with the given limit in bytes. - /// The default limit is 128kb - public static func collect(upTo limit: Int = 128 * 1024) -> Self - /// Subprocess should write the child process output - /// to the file descriptor specified. - /// - Parameters: - /// - fd: the file descriptor to write to - /// - closeAfterSpawningProcess: whether to close the - /// file descriptor once the process is spawned. - public static func writeTo(_ fd: FileDescriptor, closeAfterSpawningProcess: Bool) -> Self - } +/// `OutputProtocol` specifies the set of methods that a type +/// must implement to serve as the output target for a subprocess. +/// Instead of developing custom implementations of `OutputProtocol`, +/// it is recommended to utilize the default implementations provided +/// by the `Subprocess` library to specify the output handling requirements. +public protocol OutputProtocol: Sendable { + associatedtype OutputType: Sendable + /// Lazily create and return the FileDescriptor for reading + func readFileDescriptor() throws -> FileDescriptor? + /// Lazily create and return the FileDescriptor for writing + func writeFileDescriptor() throws -> FileDescriptor? + /// Return the read `FileDescriptor` and remove it from the output + /// such that the next call to `consumeReadFileDescriptor` will + /// return `nil`. + func consumeReadFileDescriptor() -> FileDescriptor? + + /// Close the FileDescriptor for reading + func closeReadFileDescriptor() throws + /// Close the FileDescriptor for writing + func closeWriteFileDescriptor() throws + + /// Capture the output from the subprocess + func captureOutput() async throws -> OutputType +} + +/// `ManagedOutputProtocol` is managed by `Subprocess` and +/// utilizes its `Pipe` type to facilitate output reading. +/// Developers have the option to implement custom input types +/// by conforming to `ManagedOutputProtocol` +/// and implementing the `output(from:)` method. +@available(macOS 9999, *) // Span equivelent +public protocol ManagedOutputProtocol: OutputProtocol { + /// The underlying pipe used by this output in order to + /// read from the child process + var pipe: Pipe { get } + + /// Convert the output from Data to expected output type + func output(from span: RawSpan) throws -> OutputType + /// The max amount of data to collect for this output. + var maxSize: Int { get } +} + +/// A concrete `Output` type for subprocesses that indicates that +/// the `Subprocess` should not collect or redirect output +/// from the child process. On Unix-like systems, `DiscardedOutput` +/// redirects the standard output of the subprocess to `/dev/null`, +/// while on Windows, it does not bind any file handle to the +/// subprocess standard output handle. +public struct DiscardedOutput: OutputProtocol { } + +/// A concrete `Output` type for subprocesses that +/// writes output to a specified `FileDescriptor`. +/// Developers have the option to instruct the `Subprocess` to +/// automatically close the provided `FileDescriptor` +/// after the subprocess is spawned. +public struct FileDescriptorOutput: OutputProtocol { } + +/// A concrete `Output` type for subprocesses that collects output +/// from the subprocess as `String` with the given encoding. +/// This option must be used with he `run()` method that +/// returns a `CollectedResult`. +@available(macOS 9999, *) // Span equivelent +public struct StringOutput: ManagedOutputProtocol { } + +/// A concrete `Output` type for subprocesses that collects output +/// from the subprocess as `[UInt8]`. This option must be used with +/// the `run()` method that returns a `CollectedResult` +@available(macOS 9999, *) +public final class BytesOutput: ManagedOutputProtocol { } + +/// A concrete `Output` type for subprocesses that redirects +/// the child output to the `.standardOutput` or `.standardError` +/// property of `Execution`. This output type is +/// only applicable to the `run()` family that takes a custom closure. +public struct SequenceOutput: OutputProtocol { } + + +extension OutputProtocol where Self == DiscardedOutput { + /// Create a Subprocess output that discards the output + public static var discarded: Self { } +} + +extension OutputProtocol where Self == FileDescriptorOutput { + /// Create a Subprocess output that writes output to a `FileDescriptor` + /// and optionally close the `FileDescriptor` once process spawned. + public static func fileDescriptor( + _ fd: FileDescriptor, + closeAfterSpawningProcess: Bool + ) -> Self +} + +extension OutputProtocol where Self == SequenceOutput { + /// Create a `Subprocess` output that redirects the output + /// to the `.standardOutput` (or `.standardError`) property + /// of `Execution` as `AsyncSequence`. + public static var sequence: Self { .init() } +} + +@available(macOS 9999, *) // Span equivelent +extension OutputProtocol { + /// Create a `Subprocess` output that collects output as + /// UTF8 String with 128kb limit. + public static func string() -> Self where Self == StringOutput + + /// Create a `Subprocess` output that collects output as + /// `String` using the given encoding up to limit it bytes. + public static func string( + limit: Int, + encoding: Encoding.Type + ) -> Self where Self == StringOutput +} + +@available(macOS 9999, *) // Span equivelent +extension OutputProtocol where Self == BytesOutput { + /// Create a `Subprocess` output that collects output as + /// `Buffer` with 128kb limit. + public static var bytes: Self + + /// Create a `Subprocess` output that collects output as + /// `Buffer` up to limit it bytes. + public static func bytes(limit: Int) -> Self } ``` -On the other hand, `RedirectedOutputMethod` adds one more option, `.redirectToSequence`, to the closure-based `run` methods to signify that output should be redirected to the `.standardOutput` or `.standardError` property of `Subprocess` passed to the closure as `AsyncSequence`. Since `AsyncSequence` is not push-based, there is no byte limit for this option: + +`SubprocessFoundation` adds one additional concrete input: + +- `DataOutput`: collects output from the subprocess as `Data`. + ```swift -extension Subprocess { - /// `CollectedOutputMethod` defines how should Subprocess redirect - /// output from child process' standard output and standard error. - @available(FoundationPreview 0.4, *) - @available(iOS, unavailable) - @available(tvOS, unavailable) - @available(watchOS, unavailable) - public struct RedirectedOutputMethod: Sendable, Hashable { - /// Subprocess shold dicard the child process output. - /// This option is equivalent to binding the child process - /// output to `/dev/null`. - public static var discard: Self - /// Subprocess should redirect the child process output - /// to `Subprocess.standardOutput` or `Subprocess.standardError` - /// so they can be consumed as an AsyncSequence - public static var redirectToSequence: Self - /// Subprocess shold write the child process output - /// to the file descriptor specified. - /// - Parameters: - /// - fd: the file descriptor to write to - /// - closeAfterSpawningProcess: whether to close the - /// file descriptor once the process is spawned. - public static func writeTo(_ fd: FileDescriptor, closeAfterSpawningProcess: Bool) -> Self +import Foundation + +/// A concrete `Output` type for subprocesses that collects output +/// from the subprocess as `Data`. This option must be used with +/// the `run()` method that returns a `CollectedResult` +@available(macOS 9999, *) // Span equivelent +public struct DataOutput: ManagedOutputProtocol { } + +@available(macOS 9999, *) // Span equivelent +extension OutputProtocol where Self == DataOutput { + /// Create a `Subprocess` output that collects output as `Data` + /// up to 128kb. + public static var data: Self { + return .data(limit: 128 * 1024) + } + + /// Create a `Subprocess` output that collects output as `Data` + /// with given max number of bytes to collect. + public static func data(limit: Int) -> Self { + return .init(limit: limit) } } ``` -Here are some examples of using both output methods: +Here are some examples of using different outputs: ```swift -let ls = try await Subprocess.run(.named("ls"), output: .collect()) -// The output has been collected as `Data`, up to 16kb limit -print("ls output: \(String(data: ls.standardOutput, encoding: .utf8)!)") - -// Increase the default buffer limit to 256kb -let curl = try await Subprocess.run( - .named("curl"), - output: .collect(upTo: 256 * 1024) +let ls = try await run(.name("ls"), output: .string) +// The output has been collected as `String`, up to 128kb limit +print("ls output: \(ls.standardOutout!)") + +// Increase the default buffer limit to 256kb and collect output as Data +let curl = try await run( + .name("curl"), + output: .data(limit: 256 * 1024) ) -print("curl output: \(String(data: curl.standardOutput, encoding: .utf8)!)") +print("curl output: \(curl.standardOutput.count)") + // Write to a specific file descriptor let fd: FileDescriptor = try .open(...) -let result = try await Subprocess.run( - .at("/some/script"), output: .writeTo(fd, closeAfterSpawningProcess: true)) - -// Redirect the output as AsyncSequence -let result2 = try await Subprocess.run( - .named("/some/script"), output: .redirectToSequence -) { subprocess in - // Output can be access via `subprocess.standardOutput` here - for try await item in subprocess.standardOutput { - print(item) +let result = try await run( + .path("/some/script"), + output: .fileDescriptor(fd, closeAfterSpawningProcess: true) +) +``` + + +### `SequenceOutput.Buffer` + +When utilizing the closure-based `run()` method with `SequenceOutput`, developers have the option to ‘stream’ the standard output or standard error of the subprocess as an `AsyncSequence`. To enhance performance, it’s more efficient to stream a collection of bytes at once rather than individually. Since the core `Subprocess` module doesn’t rely on `Foundation`, we propose introducing a simple `struct Buffer` to serve as our ‘collection of bytes’. This `Buffer` enables `Subprocess` to reduce the frequency of data copying by maintaining references to internal data types. + +```swift +extension SequenceOutput { + /// A immutable collection of bytes + public struct Buffer: Sendable, Hashable, Equatable { + /// Number of bytes stored in the buffer + public var count: Int { get } + + /// A Boolean value indicating whether the collection is empty. + public var isEmpty: Bool { get } + + /// Access the raw bytes stored in this buffer + /// - Parameter body: A closure with an `UnsafeRawBufferPointer` parameter that + /// points to the contiguous storage for the type. If no such storage exists, + /// the method creates it. If body has a return value, this method also returns + /// that value. The argument is valid only for the duration of the + /// closure’s execution. + /// - Returns: The return value, if any, of the body closure parameter. + public func withUnsafeBytes( + _ body: (UnsafeRawBufferPointer) throws -> ResultType + ) rethrows -> ResultType + + /// Access the bytes stored in this buffer as `RawSpan` + @available(macOS 9999, *) // Span equivalent + var bytes: RawSpan { get } } - return "Done" } + ``` -**Note**: Accessing `.standardOutput` or `.standardError` on `Subprocess` or `CollectedResult` (described below) without setting the corresponding `OutputMethod` to `.redirectToSequence` or `.collect` will result in a **fatalError**. This is considered a programmer error because source code changes are needed to fix it. +`Buffer` is designed specifically to meet the specific needs of `Subprocess` rather than serving as a general-purpose byte container. It’s immutable, and the main method to access data from a `Buffer` is through `RawSpan`. + +```swift +let catResult = try await Subprocess.run( + .path("..."), + output: .sequence, + error: .discarded +) { execution in + for try await chunk in execution.standardOutput { + // Pending String RawSpan support + let value = String(chunk.bytes, as: UTF8.self) + if value.contains("Done") { + await execution.teardown( + using: [ + .sendSignal(.quit, allowedDurationToExit: .milliseconds(500)), + ] + ) + return true + } + } + return false +} +``` ### Result Types -`Subprocess` provides two "Result" types corresponding to the two categories of `run` methods: `Subprocess.CollectedResult` and `Subprocess.ExecutionResult`. +`Subprocess` provides two "Result" types corresponding to the two categories of `run` methods: `CollectedResult` and `ExecutionResult`. -`Subprocess.CollectedResult` is essentially a collection of properties that represent the result of an execution after the child process has exited. It is used by the non-closure-based `run` methods. In many ways, `CollectedResult` can be seen as the "synchronous" version of `Subprocess`—instead of the asynchronous `AsyncSequence`, the standard IOs can be retrieved via synchronous `Data`. +`CollectedResult` is essentially a collection of properties that represent the result of an execution after the child process has exited. It is used by the non-closure-based `run` methods. In many ways, `CollectedResult` can be seen as the "synchronous" version of `Subprocess`—instead of the asynchronous `AsyncSequence`, the standard IOs can be retrieved via synchronous `Buffer` or `String?`. ```swift -extension Subprocess { - /// The result of a subprocess execution with its collected - /// standard output and standard error. - @available(FoundationPreview 0.4, *) - @available(iOS, unavailable) - @available(tvOS, unavailable) - @available(watchOS, unavailable) - public struct CollectedResult: Sendable, Hashable, Codable { - /// The process identifier for the executed subprocess - public let processIdentifier: ProcessIdentifier - /// The termination status of the executed subprocess - public let terminationStatus: TerminationStatus - /// The collected standard output value for the subprocess. - /// Accessing this property will *fatalError* if the - /// corresponding `CollectedOutputMethod` is not set to - /// `.collect` or `.collect(upTo:)` - public let standardOutput: Data - /// The collected standard error value for the subprocess. - /// Accessing this property will *fatalError* if the - /// corresponding `CollectedOutputMethod` is not set to - /// `.collect` or `.collect(upTo:)` - public let standardError: Data - } +/// The result of a subprocess execution with its collected +/// standard output and standard error. +public struct CollectedResult< + Output: OutputProtocol, + Error: OutputProtocol +>: Sendable { + /// The process identifier for the executed subprocess + public let processIdentifier: ProcessIdentifier + /// The termination status of the executed subprocess + public let terminationStatus: TerminationStatus + public let standardOutput: Output.OutputType + public let standardError: Error.OutputType } -extension Subprocess.CollectedResult : CustomStringConvertible, CustomDebugStringConvertible {} +extension CollectedResult: Equatable where Output.OutputType: Equatable, Error.OutputType: Equatable {} + +extension CollectedResult: Hashable where Output.OutputType: Hashable, Error.OutputType: Hashable {} + +extension CollectedResult: Codable where Output.OutputType: Codable, Error.OutputType: Codable {} + +extension CollectedResult: CustomStringConvertible where Output.OutputType: CustomStringConvertible, Error.OutputType: CustomStringConvertible ``` -`Subprocess.ExecutionResult` is a simple wrapper around the generic result returned by the `run` closures with the corresponding `TerminationStatus` of the child process: +`ExecutionResult` is a simple wrapper around the generic result returned by the `run` closures with the corresponding `TerminationStatus` of the child process: ```swift -extension Subprocess { - /// A simple wrapper around the generic result returned by the - /// `run` closures with the corresponding `TerminationStatus` - /// of the child process. - @available(FoundationPreview 0.4, *) - @available(iOS, unavailable) - @available(tvOS, unavailable) - @available(watchOS, unavailable) - public struct ExecutionResult: Sendable { - /// The termination status of the child process - public let terminationStatus: TerminationStatus - /// The result returned by the closure passed to `.run` methods - public let value: T - } +/// A simple wrapper around the generic result returned by the +/// `run` closures with the corresponding `TerminationStatus` +/// of the child process. +public struct ExecutionResult { + /// The termination status of the child process + public let terminationStatus: TerminationStatus + /// The result returned by the closure passed to `.run` methods + public let value: Result } -@available(FoundationPreview 0.4, *) -@available(iOS, unavailable) -@available(tvOS, unavailable) -@available(watchOS, unavailable) -extension Subprocess.ExecutionResult: Equatable where T : Equatable {} - -@available(FoundationPreview 0.4, *) -@available(iOS, unavailable) -@available(tvOS, unavailable) -@available(watchOS, unavailable) -extension Subprocess.ExecutionResult : Hashable where T : Hashable {} - -@available(FoundationPreview 0.4, *) -@available(iOS, unavailable) -@available(tvOS, unavailable) -@available(watchOS, unavailable) -extension Subprocess.ExecutionResult : Codable where T : Codable {} - -@available(FoundationPreview 0.4, *) -@available(iOS, unavailable) -@available(tvOS, unavailable) -@available(watchOS, unavailable) -extension Subprocess.ExecutionResult: CustomStringConvertible where T : CustomStringConvertible {} - -@available(FoundationPreview 0.4, *) -@available(iOS, unavailable) -@available(tvOS, unavailable) -@available(watchOS, unavailable) -extension Subprocess.ExecutionResult: CustomDebugStringConvertible where T : CustomDebugStringConvertible {} +extension ExecutionResult: Equatable where Result : Equatable {} + +extension ExecutionResult : Hashable where Result : Hashable {} + +extension ExecutionResult : Codable where Result : Codable {} + +extension ExecutionResult: CustomStringConvertible where Result : CustomStringConvertible {} + +extension ExecutionResult: CustomDebugStringConvertible where Result : CustomDebugStringConvertible {} ``` -### `Subprocess.Executable` +### `Executable` -`Subprocess` utilizes `Executable` to configure how the executable is resolved. Developers can create an `Executable` using two static methods: `.named()`, indicating that an executable name is provided, and `Subprocess` should try to automatically resolve the executable path, and `.at()`, signaling that an executable path is provided, and `Subprocess` should use it unmodified. +`Subprocess` utilizes `Executable` to configure how the executable is resolved. Developers can create an `Executable` using two static methods: `.name()`, indicating that an executable name is provided, and `Subprocess` should try to automatically resolve the executable path, and `.path()`, signaling that an executable path is provided, and `Subprocess` should use it unmodified. ```swift -extension Subprocess { - /// `Subprocess.Executable` defines how should the executable - /// be looked up for execution. - @available(FoundationPreview 0.4, *) - @available(iOS, unavailable) - @available(tvOS, unavailable) - @available(watchOS, unavailable) - public struct Executable: Sendable, Hashable { - /// Locate the executable by its name. - /// `Subprocess` will use `PATH` value to - /// determine the full path to the executable. - public static func named(_ executableName: String) -> Self - /// Locate the executable by its full path. - /// `Subprocess` will use this path directly. - public static func at(_ filePath: FilePath) -> Self - /// Returns the full executable path given the environment value. - public func resolveExecutablePath(in environment: Environment) -> FilePath? - } +/// `Executable` defines how should the executable +/// be looked up for execution. +public struct Executable: Sendable, Hashable { + /// Locate the executable by its name. + /// `Subprocess` will use `PATH` value to + /// determine the full path to the executable. + public static func name(_ executableName: String) -> Self + /// Locate the executable by its full path. + /// `Subprocess` will use this path directly. + public static func path(_ filePath: FilePath) -> Self + /// Returns the full executable path given the environment value. + public func resolveExecutablePath(in environment: Environment) throws -> FilePath } -extension Subprocess.Executable : CustomStringConvertible, CustomDebugStringConvertible {} +extension Executable : CustomStringConvertible, CustomDebugStringConvertible {} ``` -### `Subprocess.Environment` +### `Environment` `struct Environment` is used to configure how should the process being launched receive its environment values: ```swift -extension Subprocess { - @available(FoundationPreview 0.4, *) - @available(iOS, unavailable) - @available(tvOS, unavailable) - @available(watchOS, unavailable) - public struct Environment: Sendable, Hashable { - /// Child process should inherit the same environment - /// values from its parent process. - public static var inherit: Self { get } - /// Override the provided `newValue` in the existing `Environment` - public func updating( - _ newValue: [String : String] - ) -> Self - /// Use custom environment variables - public static func custom( - _ newValue: [String : String] - ) -> Self +public struct Environment: Sendable, Hashable { + /// Child process should inherit the same environment + /// values from its parent process. + public static var inherit: Self { get } + /// Override the provided `newValue` in the existing `Environment` + public func updating( + _ newValue: [String : String] + ) -> Self + /// Use custom environment variables + public static func custom( + _ newValue: [String : String] + ) -> Self #if !os(Windows) - /// Override the provided `newValue` in the existing `Environment` - public func updating( - _ newValue: [Data : Data] - ) -> Self - /// Use custom environment variables - public static func custom( - _ newValue: [Data : Data] - ) -> Self + /// Use custom environment variables of raw bytes + public static func custom(_ newValue: Array<[UInt8]>) -> Self #endif // !os(Windows) - } } -extension Subprocess.Environment : CustomStringConvertible, CustomDebugStringConvertible {} +extension Environment : CustomStringConvertible, CustomDebugStringConvertible {} ``` Developers have the option to: @@ -1396,16 +1578,16 @@ Developers have the option to: ```swift // Override the `PATH` environment value from launching process -let result = try await Subprocess.run( - .at("/some/executable"), +let result = try await run( + .path("/some/executable"), environment: .inherit.updating( ["PATH" : "/some/new/path"] ) ) // Use custom values -let result2 = try await Subprocess.run( - .at("/at"), +let result2 = try await run( + .path("/at"), environment: .custom([ "PATH" : "/some/path" "HOME" : "/Users/Charles" @@ -1416,64 +1598,57 @@ let result2 = try await Subprocess.run( `Environment` is designed to support both `String` and raw bytes for the use case where the environment values might not be valid UTF8 strings *on Unix like systems (macOS and Linux)*. Windows requires environment values to `CreateProcessW` to be valid String and therefore only supports the String variant. -### `Subprocess.Arguments` +### `Arguments` -`Subprocess.Arguments` is used to configure the spawn arguments sent to the child process. It conforms to `ExpressibleByArrayLiteral`. In most cases, developers can simply pass in an array `[String]` with the desired arguments. However, there might be scenarios where a developer wishes to override the first argument (i.e., the executable path). This is particularly useful because some processes might behave differently based on the first argument provided. The ability to override the executable path can be achieved by specifying the `pathOverride` parameter: +`Arguments` is used to configure the spawn arguments sent to the child process. It conforms to `ExpressibleByArrayLiteral`. In most cases, developers can simply pass in an array `[String]` with the desired arguments. However, there might be scenarios where a developer wishes to override the first argument (i.e., the executable path). This is particularly useful because some processes might behave differently based on the first argument provided. The ability to override the executable path can be achieved by specifying the `pathOverride` parameter: ```swift -extension Subprocess { - /// A collection of arguments to pass to the subprocess. - @available(FoundationPreview 0.4, *) - @available(iOS, unavailable) - @available(tvOS, unavailable) - @available(watchOS, unavailable) - public struct Arguments: Sendable, ExpressibleByArrayLiteral, Hashable { - public typealias ArrayLiteralElement = String - /// Creates an Arguments object using the given literal values - public init(arrayLiteral elements: ArrayLiteralElement...) - /// Creates an Arguments object using the given array - public init(_ array: [ArrayLiteralElement]) +/// A collection of arguments to pass to the subprocess. +public struct Arguments: Sendable, ExpressibleByArrayLiteral, Hashable { + public typealias ArrayLiteralElement = String + /// Creates an Arguments object using the given literal values + public init(arrayLiteral elements: ArrayLiteralElement...) + /// Creates an Arguments object using the given array + public init(_ array: [ArrayLiteralElement]) #if !os(Windows) - /// Create an `Argument` object using the given values, but - /// override the first Argument value to `executablePathOverride`. - /// If `executablePathOverride` is nil, - /// `Arguments` will automatically use the executable path - /// as the first argument. - /// - Parameters: - /// - executablePathOverride: the value to override the first argument. - /// - remainingValues: the rest of the argument value - public init(executablePathOverride: String?, remainingValues: [String]) - /// Creates an Arguments object using the given array - public init(_ array: [Data]) - /// Create an `Argument` object using the given values, but - /// override the first Argument value to `executablePathOverride`. - /// If `executablePathOverride` is nil, - /// `Arguments` will automatically use the executable path - /// as the first argument. - /// - Parameters: - /// - executablePathOverride: the value to override the first argument. - /// - remainingValues: the rest of the argument value - public init(executablePathOverride: Data?, remainingValues: [Data]) + /// Create an `Argument` object using the given values, but + /// override the first Argument value to `executablePathOverride`. + /// If `executablePathOverride` is nil, + /// `Arguments` will automatically use the executable path + /// as the first argument. + /// - Parameters: + /// - executablePathOverride: the value to override the first argument. + /// - remainingValues: the rest of the argument value + public init(executablePathOverride: String?, remainingValues: [String]) + /// Creates an Arguments object using the given array + public init(_ array: Array<[UInt8]>) + /// Create an `Argument` object using the given values, but + /// override the first Argument value to `executablePathOverride`. + /// If `executablePathOverride` is nil, + /// `Arguments` will automatically use the executable path + /// as the first argument. + /// - Parameters: + /// - executablePathOverride: the value to override the first argument. + /// - remainingValues: the rest of the argument value + public init(executablePathOverride: [UInt8]?, remainingValues: Array<[UInt8]>) #endif // !os(Windows) - } -} -extension Subprocess.Arguments : CustomStringConvertible, CustomDebugStringConvertible {} +extension Arguments : CustomStringConvertible, CustomDebugStringConvertible {} ``` Similar to `Environment`, `Arguments` also supports raw bytes in addition to `String` *on Unix like systems (macOS and Linux)*. Windows requires argument values passed to `CreateProcessW` to be valid String and therefore only supports the String variant. ```swift // In most cases, simply pass in an array -let result = try await Subprocess.run( - .at("/some/executable"), +let result = try await run( + .path("/some/executable"), arguments: ["arg1", "arg2"] ) // Override the executable path -let result2 = try await Subprocess.run( - .at("/some/executable"), +let result2 = try await run( + .path("/some/executable"), arguments: .init( executablePathOverride: "/new/executable/path", remainingValues: ["arg1", "arg2"] @@ -1482,39 +1657,84 @@ let result2 = try await Subprocess.run( ``` -### `Subprocess.TerminationStatus` +### `TerminationStatus` + +`TerminationStatus` is used to communicate the exit statuses of a process: `exited` and `unhandledException`. + +```swift +@frozen +public enum TerminationStatus: Sendable, Hashable, Codable { +#if canImport(WinSDK) + public typealias Code = DWORD +#else + public typealias Code = CInt +#endif + /// The subprocess was existed with the given code + case exited(Code) + /// The subprocess was signalled with given exception value + case unhandledException(Code) + + /// Whether the current TerminationStatus is successful. + public var isSuccess: Bool +} +extension TerminationStatus : CustomStringConvertible, CustomDebugStringConvertible {} +``` + +### `SubprocessError` -`Subprocess.TerminationStatus` is used to communicate the exit statuses of a process: `exited` and `unhandledException`. +`Subprocess` provides its own error type, `SubprocessError`, which encapsulates all errors generated by `Subprocess`. These errors are instances of `SubprocessError` with an optional `underlyingError` attribute. On Unix-like systems (including Darwin and Linux), `Subprocess` exposes `SubprocessError.POSIXError` as a straightforward wrapper around `errno` that serve as the `underlyingError`. In contrast, on Windows, `Subprocess` utilizes `WindowsError`, which wraps Windows error codes as the `underlyingError`. ```swift +/// Error thrown from Subprocess +public struct SubprocessError: Swift.Error, Hashable, Sendable { + /// The error code of this error + public let code: SubprocessError.Code + /// The underlying error that caused this error, if any + public let underlyingError: UnderlyingError? +} + extension Subprocess { - @available(FoundationPreview 0.4, *) - @available(iOS, unavailable) - @available(tvOS, unavailable) - @available(watchOS, unavailable) - @frozen - public enum TerminationStatus: Sendable, Hashable, Codable { - #if canImport(WinSDK) - public typealias Code = DWORD - #else - public typealias Code = CInt - #endif - /// The subprocess was existed with the given code - case exited(Code) - /// The subprocess was signalled with given exception value - case unhandledException(Code) - - /// Whether the current TerminationStatus is successful. - public var isSuccess: Bool + /// A SubprocessError Code + public struct Code: Hashable, Sendable { + public let value: Int + } +} + +extension SubprocessError: CustomStringConvertible, CustomDebugStringConvertible {} + +extension SubprocessError { + /// The underlying error that caused this SubprocessError. + /// - On Unix-like systems, `UnderlyingError` wraps `errno` from libc; + /// - On Windows, `UnderlyingError` wraps Windows Error code + public struct UnderlyingError: Swift.Error, RawRepresentable, Hashable, Sendable { +#if os(Window) + public typealias RawValue = DWORD +#else + public typealias RawValue = Int32 +#endif + + public let rawValue: RawValue + public init(rawValue: RawValue) } } -extension Subprocess.TerminationStatus : CustomStringConvertible, CustomDebugStringConvertible {} +``` + + +### `Pipe` + +`Subprocess` provides an opaque `Pipe` type that creates and manages Unix-like pipes (file descriptor pairs for read and write operations) used by `Subprocess` for communication with child processes. The `Pipe` type is designed to be exclusively utilized by `ManagedInputProtocol` and `ManagedOutputProtocol` as an implementation detail. + +```swift +/// A managed, opaque UNIX pipe used by `PipeOutputProtocol` and `PipeInputProtocol` +public final class Pipe: Sendable { + public init() {} +} ``` ### Task Cancellation -If the task running `Subprocess.run` is cancelled while the child process is running, `Subprocess` will attempt to release all the resources it acquired (i.e. file descriptors) and then terminate the child process via `SIGKILL`. +If the task running `Subprocess.run` is cancelled while the child process is running, `Subprocess` will attempt to release all the resources it acquired (i.e. file descriptors) and then terminate the child process according to the `TeardownSequence`. ## Impact on Existing Code @@ -1544,18 +1764,19 @@ With the current design, the recommended way to "pipe" the output of one process ```swift let pipe = try FileDescriptor.pipe() -async let ls = try await Subprocess.run( - .named("ls"), +async let ls = try await run( + .name("ls"), output: .writeTo(pipe.writeEnd, closeAfterSpawningProcess: true) ) -async let grep = try await Subprocess.run( - .named("grep"), +async let grep = try await run( + .name("grep"), arguments: ["swift"], - input: .readFrom(pipe.readEnd, closeAfterSpawningProcess: true) + input: .readFrom(pipe.readEnd, closeAfterSpawningProcess: true), + output: .collectString() ) -let result = await String(data: grep.standardOutput, encoding: .utf8) +let result = await grep.standardOutput ``` This setup is overly complex for such a simple operation in shell script (`ls | grep "swift"`). We should reimagine how piping should work with `Subprocess` next.