[Feature] Add timeout parameter and TimeoutError to run API

[newamber]

Is your feature request related to a problem? Please describe.
When executing external processes using the run API, there's currently no way to set a time limit for their execution. This can be problematic if a subprocess becomes unresponsive or takes an excessively long time to complete, potentially leading to the calling application hanging indefinitely or consuming excessive resources.

Describe the solution you'd like
I'd like to propose adding a timeout parameter to the run API. If the subprocess execution time exceeds this specified timeout value, the run function should throw a new error type, perhaps named TimeoutError. This would allow users to gracefully handle scenarios where a subprocess exceeds its expected execution time. Upon catching a TimeoutError, users could then choose to inspect the process's PID (if available) and programmatically terminate the hanging process if necessary.

Describe alternatives you've considered
Currently, managing timeouts would require implementing custom timer mechanisms and process monitoring outside of swift-subprocess, which adds complexity and boilerplate code for a common use case.

Additional context
This feature is inspired by similar functionality found in other languages' subprocess libraries. For example, Python's subprocess.run function offers a timeout parameter and raises a TimeoutExpired exception, providing a robust way to manage long-running processes. You can refer to the Python documentation here: https://docs.python.org/3.13/library/subprocess.html#using-the-subprocess-module

[iCharlesHu]

Hi @newamber! Thanks for the suggestion. Great idea!

[FranzBusch]

I would recommend that we go the other way around since Subrpocess.run respects cancellation we can compose it around. If you can write yourself a general purpose timeout method like this:

public func withTimeout<T: Sendable, Clock: _Concurrency.Clock>(
    in timeout: Clock.Duration,
    clock: Clock,
    isolation: isolated (any Actor)? = #isolation,
    body: @escaping () async throws -> T
) async throws -> T {

Then you can just wrap the Subprocess.run inside it and it will get properly cancelled. This avoids all methods in the ecosystem to add such timeout parameters and instead allows us to compose it.

[newamber]

I would recommend that we go the other way around since respects cancellation we can compose it around. If you can write yourself a general purpose timeout method like this:Subrpocess.run

public func withTimeout<T: Sendable, Clock: _Concurrency.Clock>(
    in timeout: Clock.Duration,
    clock: Clock,
    isolation: isolated (any Actor)? = #isolation,
    body: @escaping () async throws -> T
) async throws -> T {

Then you can just wrap the inside it and it will get properly cancelled. This avoids all methods in the ecosystem to add such parameters and instead allows us to compose it.Subprocess.run``timeout

That makes a lot of sense, so theoretically, this function should be provided by Swift's standard library?

[FranzBusch]

That makes a lot of sense, so theoretically, this function should be provided by Swift's standard library?

It can be provided by many places. In the standard library we might want to explore if we can integrate this even more with concurrency. swift-async-algorithms would be another good place but you can also just add that method in your code.

[jakepetroules]

Strongly agree with @FranzBusch that timeout does not need to be part of Subprocess itself.

[ktoso]

Swift will definitely include a deadline mechanism in swift concurrency but it’s not clear yet if we’ll get to it this release or not. Best thing to do here is to make your APIs respect and react to cancellation, and if you’ll need a workaround to trigger it from a timeout/deadline that’s an api we could deprecate in the future.