README

A high-performance async/parallel library for PHP 8.1+ providing Promises/A+ compliant promises and true multi-core parallel execution.

Features

Promise API - Promises/A+ compliant with then(), catch(), finally(), await()
Parallel Execution - True multi-core parallelism using threads and processes
Automatic Adapter Selection - Chooses optimal strategy based on runtime environment
Closure Support - Execute closures across process boundaries
Built-in Safety - Timeouts, deadlock detection, memory management

Installation

composer require utopia-php/async

Requirements

PHP 8.1+

Optional Extensions (for parallel execution)

Extension/Package	Required For
`ext-swoole` >=6.0 + ZTS	Swoole Thread adapter (best performance)
`ext-swoole` + `ext-sockets`	Swoole Process adapter
`ext-parallel` + ZTS	ext-parallel adapter
`amphp/parallel`	Amp adapter
`react/child-process`	React adapter

Promise API

Promises provide asynchronous operations with coroutine support when Swoole is available, falling back to synchronous execution otherwise.

Basic Usage

use Utopia\Async\Promise;

// Execute and get result
$result = Promise::run(fn() => 42); // Returns: 42

// Async execution with chaining
Promise::async(fn() => 10)
    ->then(fn($v) => $v * 2)
    ->then(fn($v) => $v + 5)
    ->catch(fn($e) => error_log($e->getMessage()))
    ->finally(fn() => cleanup())
    ->await(); // Returns: 25

// Execute multiple callables concurrently
$results = Promise::map([
    fn() => fetchUser(),
    fn() => fetchPosts(),
    fn() => fetchComments(),
])->await(); // [user, posts, comments]

Promise Methods

// Create resolved/rejected promises
$resolved = Promise::resolve('value');
$rejected = Promise::reject(new Exception('error'));

// Delay execution
Promise::delay(1000)->await(); // Wait 1 second

// Timeout wrapper
Promise::async(fn() => longOperation())
    ->timeout(5000) // 5 second timeout
    ->catch(fn($e) => handleTimeout())
    ->await();

Collection Methods

// Wait for all promises
$results = Promise::all([
    Promise::async(fn() => fetchUser()),
    Promise::async(fn() => fetchPosts()),
    Promise::async(fn() => fetchComments()),
])->await(); // [user, posts, comments]

// First to settle wins
$fastest = Promise::race([
    Promise::async(fn() => primaryApi()),
    Promise::async(fn() => fallbackApi()),
])->await();

// Get all results regardless of success/failure
$results = Promise::allSettled([
    Promise::async(fn() => maySucceed()),
    Promise::async(fn() => mayFail()),
])->await();
// [
//   ['status' => 'fulfilled', 'value' => ...],
//   ['status' => 'rejected', 'reason' => Exception]
// ]

// First successful result
$value = Promise::any([
    Promise::async(fn() => tryFirst()),
    Promise::async(fn() => trySecond()),
])->await();

Parallel API

Parallel execution distributes work across CPU cores using threads or processes.

Basic Usage

use Utopia\Async\Parallel;

// Single task
$result = Parallel::run(fn() => expensiveCalculation());

// With arguments
$result = Parallel::run(fn($x, $y) => $x + $y, 10, 20); // Returns: 30

// Multiple tasks
$results = Parallel::all([
    fn() => task1(),
    fn() => task2(),
    fn() => task3(),
]); // [result1, result2, result3]

Map and ForEach

$items = [1, 2, 3, 4, 5, 6, 7, 8];

// Parallel map - transforms each item
$squared = Parallel::map($items, fn($n) => $n ** 2);
// [1, 4, 9, 16, 25, 36, 49, 64]

// Specify worker count
$results = Parallel::map($items, fn($n) => process($n), 4); // 4 workers

// ForEach - side effects only, no return values
Parallel::forEach($files, fn($file) => processFile($file), 8);

Pool with Concurrency Control

// Limit concurrent execution
$tasks = [];
for ($i = 0; $i < 100; $i++) {
    $tasks[] = fn() => processItem($i);
}

// Max 10 concurrent tasks
$results = Parallel::pool($tasks, 10);

Lifecycle Management

The default worker pool is automatically cleaned up when the script terminates via register_shutdown_function(). You can also manually shutdown early if needed:

// Optional: manually shutdown to release resources early
Parallel::shutdown();

// Create a custom pool (not auto-cleaned, you manage its lifecycle)
$pool = Parallel::createPool(16); // 16 workers

Adapters

The library automatically selects the best adapter based on available extensions.

Promise Adapter Priority

Priority	Adapter	Runtime	Requirements
1	Swoole\Coroutine	Async	`ext-swoole`
2	React	Async	`react/event-loop`
3	Amp	Async	`amphp/amp`, `revolt/event-loop`
4	Sync	Blocking	None (fallback)

Parallel Adapter Priority

Priority	Adapter	Runtime	Requirements
1	Swoole\Thread	Multi-threaded	`ext-swoole` >=6.0 with threads, PHP ZTS
2	ext-parallel	Multi-threaded	`ext-parallel`, PHP ZTS
3	Swoole\Process	Multi-process	`ext-swoole`, `ext-sockets`
4	React	Multi-process	`react/child-process`, `react/event-loop`, `opis/closure`
5	Amp	Multi-process	`amphp/parallel`
6	Sync	Sequential	None (fallback)

Manual Adapter Selection

use Utopia\Async\Promise;
use Utopia\Async\Promise\Adapter\Sync;

Promise::setAdapter(Sync::class);

Exception Handling

use Utopia\Async\Exception\Timeout;
use Utopia\Async\Exception\Serialization;

try {
    Promise::async(fn() => riskyOperation())
        ->timeout(5000)
        ->await();
} catch (Timeout $e) {
    // Handle timeout
} catch (Serialization $e) {
    // Handle serialization failure
}

Configuration

Both Parallel and Promise facades expose configurable options via static getter/setter methods.

Parallel Configuration

use Utopia\Async\Parallel;

// Get current values
Parallel::getMaxSerializedSize();         // 10 MB (10485760 bytes)
Parallel::getMaxTaskTimeoutSeconds();     // 30 seconds
Parallel::getDeadlockDetectionInterval(); // 5 seconds
Parallel::getMemoryThresholdForGc();      // 50 MB (52428800 bytes)
Parallel::getStreamSelectTimeoutUs();     // 100ms (100000 μs)
Parallel::getWorkerSleepDurationUs();     // 10ms (10000 μs)
Parallel::getGcCheckInterval();           // 10 tasks

// Set custom values
Parallel::setMaxTaskTimeoutSeconds(60);  // Increase timeout to 60s
Parallel::setMemoryThresholdForGc(104857600); // 100 MB

// Reset all to defaults
Parallel::resetConfig();

Option	Default	Description
`MaxSerializedSize`	10 MB	Maximum payload size for task data
`MaxTaskTimeoutSeconds`	30s	Task execution timeout
`DeadlockDetectionInterval`	5s	Progress check interval for stuck workers
`MemoryThresholdForGc`	50 MB	GC trigger threshold
`StreamSelectTimeoutUs`	100ms	Non-blocking I/O timeout
`WorkerSleepDurationUs`	10ms	Worker idle sleep duration
`GcCheckInterval`	10	Tasks between GC checks

Promise Configuration

use Utopia\Async\Promise;

// Get current values
Promise::getSleepDurationUs();           // 100 μs
Promise::getMaxSleepDurationUs();        // 10ms (10000 μs)
Promise::getCoroutineSleepDurationS();   // 1ms (0.001 seconds)

// Set custom values
Promise::setSleepDurationUs(200);        // Increase initial sleep
Promise::setMaxSleepDurationUs(50000);   // 50ms max backoff

// Reset all to defaults
Promise::resetConfig();

Option	Default	Description
`SleepDurationUs`	100μs	Initial sleep for exponential backoff
`MaxSleepDurationUs`	10ms	Maximum sleep duration (backoff cap)
`CoroutineSleepDurationS`	1ms	Coroutine context sleep duration

Performance

The library achieves significant speedups for CPU-intensive and I/O-bound workloads through true parallel execution.

Running Benchmarks

Benchmarks automatically detect and test all available adapters in your environment:

# Run benchmarks with default settings (5 iterations, 50% load)
php benchmarks/Benchmark.php

# Higher iteration count for more stable results
php benchmarks/Benchmark.php --iterations=10

# Adjust workload intensity (1-100, default 50)
php benchmarks/Benchmark.php --load=75

# JSON output for charting and analysis
php benchmarks/Benchmark.php --json

# Combined options
php benchmarks/Benchmark.php --iterations=10 --load=75 --json

Adapter Comparison

Adapter	Type	Best For	Characteristics
Swoole Thread	Multi-threaded	CPU-bound tasks	Lowest overhead, shared memory
Swoole Process	Multi-process	I/O-bound tasks	Full isolation, blocking ops
Amp	Multi-process	Async I/O	Event-loop based, fibers
React	Multi-process	Async I/O	Event-loop based
ext-parallel	Multi-threaded	CPU-bound tasks	Native PHP threads
Sync	Sequential	Fallback	Always available

Benchmark Results

Results from running benchmarks with --iterations=10 --load=75 on an 8-core system:

CPU-Intensive Workloads (8 tasks)

Benchmark	Sync	Swoole Thread	Swoole Process	Amp	React
Prime calculation (300k)	0.608s	0.096s (6.4x)	0.093s (6.6x)	0.095s (6.4x)	0.146s (4.2x)
Matrix multiply (300x300)	2.957s	0.655s (4.5x)	0.494s (6.0x)	0.504s (5.9x)	0.921s (3.2x)

I/O-Simulated Workloads (8 tasks)

Benchmark	Sync	Swoole Thread	Swoole Process	Amp	React
Sleep tasks (75ms each)	0.609s	0.089s (6.8x)	0.089s (6.9x)	0.091s (6.7x)	0.103s (5.9x)
Mixed workload	0.367s	0.119s (3.1x)	0.079s (4.6x)	0.087s (4.2x)	0.105s (3.5x)

ext-parallel Benchmark Results (4-core system)

Benchmark	Sync	ext-parallel	Amp	React
Prime calculation (300k)	0.307s	0.082s (3.8x)	0.087s (3.5x)	0.098s (3.1x)
Matrix multiply (300x300)	1.453s	0.386s (3.8x)	0.380s (3.8x)	0.394s (3.7x)
Sleep tasks (75ms each)	0.305s	0.084s (3.7x)	0.087s (3.5x)	0.106s (2.9x)

Key Findings

Swoole Process achieves the best overall performance with up to 6.9x speedup on I/O workloads
Swoole Thread and Amp show comparable performance on CPU-intensive tasks (~6x speedup)
ext-parallel excels at CPU-bound tasks, achieving 3.8x speedup on a 4-core system
React provides solid multi-process execution but has higher overhead than other adapters
Parallelism overhead means single-task workloads may be slower than sequential execution
Results vary by environment - run benchmarks to find the best adapter for your use case

Development

# Run tests
composer test

# Static analysis
composer check

# Code formatting
composer format

License

MIT License. See LICENSE for details.

utopia-php / async

Maintainers

Package info

Statistics

Security

README

Features

Installation

Requirements

Optional Extensions (for parallel execution)

Promise API

Basic Usage

Promise Methods

Collection Methods

Parallel API

Basic Usage

Map and ForEach

Pool with Concurrency Control

Lifecycle Management

Adapters

Promise Adapter Priority

Parallel Adapter Priority

Manual Adapter Selection

Exception Handling

Configuration

Parallel Configuration

Promise Configuration

Performance

Running Benchmarks

Adapter Comparison

Benchmark Results

Key Findings

Development

License