Asynchronous Execution

Purpose and Scope

This document explains how to execute processes asynchronously (non-blocking) using the start() method, which allows processes to run in the background while your application continues execution. Asynchronous execution returns an InvokedProcess instance that provides methods for monitoring, controlling, and waiting for the running process.

For synchronous (blocking) execution, see Synchronous Execution. For concurrent execution of multiple processes, see Process Pools.

---

Overview

Asynchronous execution initiates a process without waiting for it to complete. This pattern is useful when:

• You need to continue application execution while the process runs
• You want to monitor process progress in real-time
• You need to control a long-running process (send signals, terminate)
• You're running multiple independent processes and want to manage them individually

The start() method returns an InvokedProcess (or FakeInvokedProcess during testing) that implements the InvokedProcessContract interface, providing methods to interact with the running process.

Sources: src/PendingProcess.php237-253

---

Execution Flow

The following diagram illustrates the complete asynchronous execution lifecycle:

Asynchronous Process Execution Flow

Sources: src/PendingProcess.php237-253 src/InvokedProcess.php1-97

---

Starting a Process Asynchronously

The start() method initiates non-blocking process execution and returns immediately with an InvokedProcessContract instance.

Method Signature

Parameters:

Parameter	Type	Description
$command	array|string|null	Command to execute (overrides configured command)
$output	?callable	Optional callback invoked with incremental output

Returns: InvokedProcessContract instance (either InvokedProcess or FakeInvokedProcess)

Throws: RuntimeException if preventStrayProcesses() is enabled and no fake handler matches

Implementation Details

The start() method follows this execution path:

1. Command Resolution - Uses provided command or falls back to configured command src/PendingProcess.php239
2. Symfony Process Creation - Converts configuration to Symfony\Component\Process\Process src/PendingProcess.php241
3. Fake Handler Check - Searches for matching fake handler src/PendingProcess.php243
4. Execution Branch:
   • Fake Path - Resolves fake handler via resolveAsynchronousFake() src/PendingProcess.php244
   • Real Path - Starts Symfony process and wraps in InvokedProcess src/PendingProcess.php252
5. Recording - Records execution if factory is in recording mode src/PendingProcess.php244-247

Sources: src/PendingProcess.php237-253

---

InvokedProcess Contract

The InvokedProcessContract interface defines the API for interacting with running processes. Both real (InvokedProcess) and fake (FakeInvokedProcess) implementations provide consistent behavior.

InvokedProcess Class Relationships

Sources: src/Contracts/InvokedProcess.php1-49 src/InvokedProcess.php1-97

---

Process State Management

Checking Process Status

The running() method determines whether the process is still executing:

Implementation:

• InvokedProcess: Delegates to $process->isRunning() src/InvokedProcess.php45-48
• FakeInvokedProcess: Simulates running state based on configured iterations

Returns: true if process is running, false if completed or not started

Getting Process ID

The id() method returns the operating system process identifier:

Implementation:

• InvokedProcess: Delegates to $process->getPid() src/InvokedProcess.php27-30
• FakeInvokedProcess: Returns fixed fake PID

Returns: Process ID if running, null if not started or terminated

Example Usage:

Sources: src/InvokedProcess.php27-30 src/InvokedProcess.php45-48 src/Contracts/InvokedProcess.php10-22

---

Output Streaming

InvokedProcess provides both cumulative and incremental output access, enabling real-time monitoring of process progress.

Output Access Methods

Cumulative Output Methods

These methods return all output accumulated since process start:

Standard Output:

• Implementation: $process->getOutput() src/InvokedProcess.php54-56
• Returns: Complete standard output buffer

Error Output:

• Implementation: $process->getErrorOutput() src/InvokedProcess.php61-64
• Returns: Complete error output buffer

Incremental Output Methods

These methods return only output produced since the last call, enabling efficient streaming:

Latest Standard Output:

• Implementation: $process->getIncrementalOutput() src/InvokedProcess.php69-72
• Returns: New standard output since last call
• Note: Each call clears the incremental buffer

Latest Error Output:

• Implementation: $process->getIncrementalErrorOutput() src/InvokedProcess.php77-80
• Returns: New error output since last call
• Note: Each call clears the incremental buffer

Output Streaming Pattern

The following table compares output access strategies:

Strategy	Methods	Use Case	Performance
Poll Cumulative	output(), errorOutput()	Read complete output after completion	Low overhead
Stream Incremental	latestOutput(), latestErrorOutput()	Real-time progress monitoring	Efficient for long processes
Callback on Start	start($cmd, $output)	Process output as it arrives	Most responsive

Sources: src/InvokedProcess.php54-80 src/Contracts/InvokedProcess.php25-42

---

Process Control: Signaling

The signal() method sends operating system signals to running processes, enabling graceful shutdown or process control.

Method Signature

Parameters:

• $signal - POSIX signal constant (e.g., SIGTERM, SIGKILL, SIGUSR1)

Returns: Self for method chaining

Implementation: Delegates to $process->signal($signal) src/InvokedProcess.php35-39

Common Signals

Signal	Constant	Value	Purpose
SIGTERM	SIGTERM	15	Request graceful termination
SIGKILL	SIGKILL	9	Force immediate termination
SIGINT	SIGINT	2	Interrupt (Ctrl+C)
SIGUSR1	SIGUSR1	10	User-defined signal 1
SIGUSR2	SIGUSR2	12	User-defined signal 2

Usage Example

Fake Process Signaling

FakeInvokedProcess records received signals for test assertions but does not actually send OS signals. This enables testing signal-based control logic without executing real processes.

Sources: src/InvokedProcess.php35-39 src/Contracts/InvokedProcess.php14-17

---

Waiting for Completion

The wait() method blocks until the process completes and returns a ProcessResult instance.

Method Signature

Parameters:

• $output - Optional callback invoked with incremental output during wait

Returns: ProcessResultContract instance with process outcome

Throws: ProcessTimedOutException if process exceeds configured timeout

Wait Behavior

Wait Execution Flow

Implementation Details

The wait() method:

1. Delegates to Symfony: Calls $process->wait($output) src/InvokedProcess.php90
2. Wraps Result: Creates ProcessResult from completed process src/InvokedProcess.php92
3. Handles Timeouts: Catches SymfonyTimeoutException and wraps in ProcessTimedOutException src/InvokedProcess.php93-94

Output Callback

The optional $output callback receives incremental output as it arrives:

Callback Signature:

Where:

• $type - Either Process::OUT (stdout) or Process::ERR (stderr)
• $buffer - Incremental output chunk

Example:

Timeout Handling

If the process exceeds the configured timeout (set via timeout() or idleTimeout()), wait() throws ProcessTimedOutException. The exception contains a ProcessResult with partial output captured before timeout.

For detailed timeout handling, see Timeout Handling.

Sources: src/InvokedProcess.php87-96 src/Contracts/InvokedProcess.php45-47

---

Fake Asynchronous Execution

During testing, start() returns FakeInvokedProcess instead of InvokedProcess when fake handlers are registered. This enables testing asynchronous logic without spawning real processes.

Fake Resolution Process

When start() encounters a matching fake handler, it invokes resolveAsynchronousFake() src/PendingProcess.php345-381:

Supported Fake Handler Return Types:

Return Type	Behavior	Line Reference
string or array	Converted to FakeProcessResult, runs 0 iterations	src/PendingProcess.php349-351
ProcessResult	Converted to FakeInvokedProcess with result data	src/PendingProcess.php353-362
FakeProcessResult	Converted to FakeInvokedProcess with result data	src/PendingProcess.php363-372
FakeProcessDescription	Used directly to create FakeInvokedProcess	src/PendingProcess.php373-374
FakeProcessSequence	Recursively resolves next sequence item	src/PendingProcess.php376-377

Throws: LogicException for unsupported return types src/PendingProcess.php380

Fake Invoked Process Characteristics

FakeInvokedProcess simulates asynchronous behavior:

• Iteration-based Running: Configured via FakeProcessDescription->runsFor(iterations), decrements each time running() is called
• Signal Recording: Stores signals sent via signal() for test verification
• Output Streaming: Simulates incremental output access
• Output Callbacks: Invokes the $output callback if provided

For detailed fake process configuration, see Fake Invoked Processes.

Recording During Fake Execution

When faking is enabled with recording, start() records the PendingProcess and predicted ProcessResult:

This enables assertions about process execution even though the process runs asynchronously. The predictProcessResult() method returns the eventual result based on fake configuration.

Sources: src/PendingProcess.php244-247 src/PendingProcess.php345-381

---

Summary

Asynchronous execution via start() provides:

• Non-blocking Execution: Application continues while process runs
• Real-time Monitoring: Access output via cumulative and incremental methods
• Process Control: Send signals for graceful/forced termination
• Flexible Waiting: Block on completion when ready with optional output callbacks
• Seamless Testing: Fake implementations mirror real behavior for deterministic tests

The InvokedProcessContract abstraction enables polymorphism between real (InvokedProcess) and fake (FakeInvokedProcess) implementations, ensuring consistent API across production and test environments.

For concurrent execution of multiple asynchronous processes, see Process Pools.

Sources: src/PendingProcess.php237-253 src/InvokedProcess.php1-97 src/Contracts/InvokedProcess.php1-49