Timeout Handling

Purpose and Scope

This document explains how to configure process timeouts, how the package detects timeout conditions, and how to handle timeout exceptions. The Hypervel Process package provides three timeout configuration methods and wraps Symfony Process timeout exceptions to provide access to partial output collected before the timeout occurred.

Timeout Configuration

The PendingProcess class provides three methods for configuring process timeouts. By default, processes have a 60-second timeout.

Timeout Configuration Methods

Method	Property Set	Default Value	Purpose
timeout(int)	$timeout	60 seconds	Maximum total execution time
idleTimeout(int)	$idleTimeout	null	Maximum time without output
forever()	$timeout	null	Disable timeout

Sources: src/PendingProcess.php45-52 src/PendingProcess.php120-148

Setting Total Execution Timeout

The timeout() method sets the maximum number of seconds the process may run:

This timeout is enforced by the underlying Symfony Process component and applies to the total execution time regardless of output activity.

Sources: src/PendingProcess.php120-128

Setting Idle Timeout

The idleTimeout() method sets the maximum number of seconds a process may run without producing output:

This is useful for processes that should produce output regularly. If the process produces no output for the specified duration, it will timeout even if the total execution time is within limits.

Sources: src/PendingProcess.php130-138

Disabling Timeout

The forever() method removes the timeout limit, allowing processes to run indefinitely:

This sets the $timeout property to null, which tells Symfony Process not to enforce any timeout.

Sources: src/PendingProcess.php140-148

Timeout Detection and Exception Flow

When a process exceeds its configured timeout, the Symfony Process component throws a SymfonyTimeoutException. The Hypervel Process package catches this exception and wraps it in a ProcessTimedOutException that includes the partial ProcessResult.

Timeout Detection Flow

Sources: src/PendingProcess.php212-230 src/PendingProcess.php267-271 src/InvokedProcess.php87-96

Synchronous Timeout Handling

In synchronous execution via run(), the timeout exception is caught and wrapped immediately:

Sources: src/PendingProcess.php226-229

Asynchronous Timeout Handling

In asynchronous execution via start() and wait(), the timeout is detected when wait() is called:

Sources: src/InvokedProcess.php89-95

ProcessTimedOutException Structure

The ProcessTimedOutException class extends Symfony's RuntimeException and wraps the original SymfonyTimeoutException while providing access to the partial ProcessResult.

Exception Components

Sources: src/Exceptions/ProcessTimedOutException.php1-27

Exception Properties

The ProcessTimedOutException provides access to:

Property	Type	Description
$result	ProcessResult	Contains partial process data collected before timeout
Message	string	Inherited from SymfonyTimeoutException
Code	int	Inherited from SymfonyTimeoutException

Sources: src/Exceptions/ProcessTimedOutException.php13-26

Accessing Partial Output from Timeout Exceptions

When a process times out, the ProcessTimedOutException provides access to any output that was collected before the timeout occurred. This partial data is available through the result property.

Partial Output Example

Sources: src/PendingProcess.php227-229 src/InvokedProcess.php89-95 src/Exceptions/ProcessTimedOutException.php13-26

Retrieving Partial Output

When catching a ProcessTimedOutException, access the result property to retrieve partial output:

The ProcessResult contained in the exception provides access to:

• command(): The command that was executed
• output(): Standard output collected before timeout
• errorOutput(): Error output collected before timeout
• exitCode(): Will be null for timed out processes

Sources: src/Exceptions/ProcessTimedOutException.php13-26

Timeout Handling Patterns

Different scenarios require different approaches to handling process timeouts.

Basic Timeout Handling

Catch and handle timeout exceptions explicitly:

Sources: src/PendingProcess.php212-230 src/Exceptions/ProcessTimedOutException.php1-27

Distinguishing Timeout from Other Failures

Use separate catch blocks to handle timeouts differently from other process failures:

Sources: src/Exceptions/ProcessTimedOutException.php1-27

Timeout Handling for Asynchronous Processes

When using start() and wait(), timeouts are detected during the wait() call:

Sources: src/InvokedProcess.php87-96

Using Idle Timeout for Hanging Processes

For processes that should produce periodic output, use idleTimeout() to detect when they hang:

Sources: src/PendingProcess.php130-138 src/PendingProcess.php269-271

Timeout Configuration Best Practices

Setting Appropriate Timeouts

Choose timeout values based on expected execution duration:

Process Type	Recommended Timeout	Example
Quick commands	5-10 seconds	File operations, simple checks
Data processing	30-60 seconds	Data transformations, API calls
Long operations	5-15 minutes	Builds, deployments
Streaming/Daemon	Use forever()	Log monitoring, background services

Sources: src/PendingProcess.php45-52

Combining Total and Idle Timeouts

Use both timeout types together for robust timeout handling:

This configuration ensures:

• The process cannot run longer than 10 minutes total
• The process must produce output at least every 60 seconds
• If the process hangs without output, it will be terminated within 60 seconds

Sources: src/PendingProcess.php120-138 src/PendingProcess.php267-271

When to Use forever()

The forever() method should be used sparingly and only for processes that truly need unlimited execution time:

Sources: src/PendingProcess.php140-148

Error Management for Asynchronous Processes

When working with asynchronous processes, error management requires special handling.

Sources: src/Contracts/ProcessResult.php7-58

Handling Errors in Asynchronous Processes

Checking Status During Execution

Conclusion

The Hypervel Process package provides a robust set of tools for error management when working with system processes. By using a combination of the detection methods, exception handling mechanisms, and error management patterns outlined in this document, you can create resilient applications that handle process failures gracefully and provide meaningful feedback to users and developers.