platform/packages/process/doc/execution.md

Process Execution

The Process package provides comprehensive features for process execution and management.

Basic Process Execution

The simplest way to execute a process is using the Factory class:

final factory = Factory();
final result = await factory.command('echo "Hello"').run();

Process Configuration

Working Directory

Set the working directory for process execution:

await factory
    .command('npm install')
    .path('/path/to/project')
    .run();

Environment Variables

Configure process environment:

await factory
    .command('node app.js')
    .env({
      'NODE_ENV': 'production',
      'PORT': '3000',
    })
    .run();

Timeouts

Set execution and idle timeouts:

await factory
    .command('long-task')
    .timeout(Duration(minutes: 5))      // Total execution timeout
    .idleTimeout(Duration(seconds: 30)) // Idle timeout
    .run();

Input/Output

Handle process input and output:

// Provide input
await factory
    .command('cat')
    .input('Hello, World!')
    .run();

// Capture output in real-time
await factory
    .command('long-task')
    .run((output) {
      print('Real-time output: $output');
    });

// Suppress output
await factory
    .command('noisy-task')
    .quietly()
    .run();

TTY Mode

Enable TTY mode for interactive processes:

await factory
    .command('interactive-script')
    .tty()
    .run();

Process Lifecycle

Starting Processes

// Run and wait for completion
final result = await factory.command('task').run();

// Start without waiting
final process = await factory.command('server').start();

Monitoring Processes

final process = await factory.command('server').start();

// Get process ID
print('PID: ${process.pid}');

// Check if running
if (await process.isRunning()) {
  print('Process is still running');
}

// Wait for completion
final result = await process.wait();

Stopping Processes

// Kill process
process.kill();

// Kill with signal
process.kill(ProcessSignal.sigterm);

// Kill after timeout
await factory
    .command('task')
    .timeout(Duration(seconds: 30))
    .run();

Error Handling

Basic Error Handling

try {
  final result = await factory
      .command('risky-command')
      .run();
      
  result.throwIfFailed();
} catch (e) {
  print('Process failed: $e');
}

Custom Error Handling

final result = await factory
    .command('task')
    .run();

result.throwIf(
  result.exitCode() != 0 || result.seeInOutput('error'),
  (result, exception) {
    // Custom error handling
    logError(result.errorOutput());
    notifyAdmin(exception);
  },
);

Timeout Handling

try {
  await factory
      .command('slow-task')
      .timeout(Duration(seconds: 5))
      .run();
} catch (e) {
  if (e is ProcessTimeoutException) {
    print('Process timed out after ${e.duration.inSeconds} seconds');
  }
}

Best Practices

1. Always set appropriate timeouts for long-running processes
2. Handle process failures and timeouts gracefully
3. Use real-time output handling for long-running processes
4. Clean up resources properly
5. Consider using quietly() for processes with noisy output
6. Set working directory and environment variables explicitly
7. Use TTY mode when interaction is needed
8. Implement proper error handling and logging
9. Consider using process pools for concurrent execution
10. Use process pipes for sequential operations

For more information on advanced features, see:

• Process Coordination for pools and pipes
• Testing Utilities for process faking and testing