happyslucker/parallel

🚀 High-performance parallel processing & async library for PHP. Process-based parallelism with promise chains, worker pools, and zero dependencies.

v2.0.0 2025-10-21 22:48 UTC

Requires

• php: ^8.3
• ext-pcntl: *
• ext-posix: *

Requires (Dev)

• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^10.0

MIT

• performance
• process
• async
• worker
• parallel
• pool
• pcntl
• concurrent
• promise
• multiprocessing

README

A powerful multiprocessing and async library for PHP that makes parallel programming simple and enjoyable! 🚀

Table of Contents 📚

• Features
• Requirements
• Installation
• Quick Start
• Core Concepts
• Examples
• Best Practices
• API Reference

Features ✨

Feature	Description
🔥 Parallel Map	Process arrays in parallel
⚡ Async Tasks	Run background tasks
🔗 Promise Chains	then()->then()->await() pattern
🎯 Process Pool	Managed worker processes
🚦 Auto Serialization	Smart data serialization
⏱️ Timeout Control	Configurable timeouts

Requirements 🛠️

Required

• PHP 8.3+ 🐘
• pcntl extension 🔧

Recommended

• msgpack extension 📦 (for better performance)

Installation 📦

composer require happyslucker/parallel

Quick Start 🚀

use Parallel\Parallel;
use Parallel\Async\Async;

// Parallel array processing
$results = Parallel::map(
    fn($item) => $item * 2,
    [1, 2, 3, 4, 5],
    4 // concurrent processes
);

print_r($results); // [2, 4, 6, 8, 10]

// Async task
$future = Async::run(function($name) {
    sleep(2);
    return "Hello, $name!";
}, ["World"]);

echo "Task running in background...\n";
$result = $future->await();
echo $result; // "Hello, World!"

Core Concepts 🧠

Process Pool Architecture 🔄

Main Process
    ├── Process Pool (Manages workers)
    │   ├── Worker 1 ──→ Task 1
    │   ├── Worker 2 ──→ Task 2  
    │   └── Worker 3 ──→ Task 3
    └── Future (Handles results)

Serialization Methods 📊

Method	⚡ Speed	📦 Size	🛠️ Requires
MsgPack	🚀 Fast	🔻 Small	ext-mspack
JSON	🐢 Slow	🔺 Large	Built-in

Examples 📖

1. Parallel Array Processing

use Parallel\Parallel;

$data = range(1, 10);

$results = Parallel::map(
    function($number) {
        usleep(100000); // Simulate work
        return [
            'number' => $number,
            'square' => $number * $number,
            'pid' => getmypid()
        ];
    },
    $data,
    4, // concurrency
    5.0 // timeout
);

foreach ($results as $result) {
    echo "Number: {$result['number']}, Square: {$result['square']}, PID: {$result['pid']}\n";
}

2. Async Tasks with Promise Chains ⛓️

use Parallel\Async\Async;

// Complex async pipeline with multiple then() chains
$future = Async::run(function() {
    echo "🏁 Starting initial task...\n";
    sleep(1);
    return 10;
})
->then(function($result) {
    echo "🔢 Processing result: $result\n";
    sleep(1);
    return $result * 2; // 20
})
->then(function($result) {
    echo "📊 Analyzing data: $result\n";
    sleep(1);
    if ($result > 15) {
        return ["status" => "success", "value" => $result + 5];
    }
    return ["status" => "error", "value" => $result];
})
->then(function($result) {
    echo "🎯 Final transformation...\n";
    sleep(1);
    if ($result['status'] === 'success') {
        return "🎉 Final result: " . $result['value'];
    }
    return "❌ Operation failed: " . $result['value'];
});

echo "⏳ Pipeline executing in background...\n";

// Wait for the entire chain to complete
$finalResult = $future->await();
echo $finalResult . "\n"; // 🎉 Final result: 25

3. Real-world Example: Data Processing Pipeline 🛠️

use Parallel\Async\Async;

// Simulate a real data processing pipeline
$processingPipeline = Async::run(function() {
    echo "📥 Step 1: Fetching user data...\n";
    sleep(2);
    return ['user_id' => 123, 'name' => 'John Doe'];
})
->then(function($userData) {
    echo "🔍 Step 2: Fetching user orders...\n";
    sleep(1);
    return [
        'user' => $userData,
        'orders' => [
            ['id' => 1, 'amount' => 100],
            ['id' => 2, 'amount' => 200]
        ]
    ];
})
->then(function($data) {
    echo "💰 Step 3: Calculating statistics...\n";
    sleep(1);
    $totalAmount = array_sum(array_column($data['orders'], 'amount'));
    return [
        'user_info' => $data['user'],
        'order_count' => count($data['orders']),
        'total_spent' => $totalAmount,
        'average_order' => $totalAmount / count($data['orders'])
    ];
})
->then(function($stats) {
    echo "📊 Step 4: Generating report...\n";
    sleep(1);
    return [
        'report' => "User {$stats['user_info']['name']} made {$stats['order_count']} " .
                   "orders totaling \${$stats['total_spent']}",
        'timestamp' => time(),
        'data' => $stats
    ];
});

// Do other work while pipeline runs
echo "🚀 Pipeline started, doing other work...\n";

// Get final result
$report = $processingPipeline->await();
echo "✅ " . $report['report'] . "\n";
echo "📅 Report generated at: " . date('Y-m-d H:i:s', $report['timestamp']) . "\n";

4. Error Handling in Chains ❌

use Parallel\Async\Async;

$future = Async::run(function() {
    echo "🎲 Rolling dice (WoW players will understand :) )...\n";
    sleep(1);
    $roll = rand(1, 6);
    if ($roll < 3) {
        throw new Exception("Bad roll: $roll! 😞");
    }
    return $roll;
})
->then(
    function($result) {
        echo "🎯 Good roll: $result\n";
        return $result * 10;
    },
    function($error) {
        echo "🛑 Error handled: {$error->getMessage()}\n";
        return 0; // Recover with default value
    }
)
->then(function($result) {
    echo "💰 Points awarded: $result\n";
    return $result;
});

$finalPoints = $future->await();
echo "🏁 Game over. Total points: $finalPoints\n";

Best Practices 🏆

Performance Optimization 🚀

Scenario	🎯 Recommended Approach	🔄 Concurrency
CPU-intensive	Parallel::map()	💻 CPU cores
I/O operations	Async::run()	⚡ Higher (8-16)
Mixed workload	🔀 Combination	🎛️ Adjustable

API Reference 📚

🏗️ Main Classes

Class	🎯 Purpose	⚙️ Methods
Parallel	🔧 Static utilities	map(), mapConcurrent(), awaitAll()
Async	⚡ Async task runner	run()
ProcessPool	👥 Process management	submit(), waitAll(), reap()
Future	📦 Result handling	await(), isRunning(), pid()
AsyncFuture	🔮 Promise-like API	await(), then(), isReady()

License 📄

MIT License - feel free to use in your projects! 💙

Author's comment

Let there be asynchronous PHP!