README

About AAsync

AAsync [Almost Async] is a high-performance, lightweight PHP library designed for parallel processing and asynchronous execution. By leveraging PCNTL forking for CPU-bound tasks and PHP Fibers for I/O-bound operations, AAsync allows you to break the synchronous barrier of PHP with a clean, modern API.

✨ Features

• Parallel CPU Processing: Execute heavy computations in separate processes using pcntl_fork.
• Fiber-based Async I/O: Non-blocking HTTP requests using Fibers and curl_multi.
• Process Pooling: Managed worker pools with a configurable concurrency limit.
• Future-based Flow: Implementation of Future objects with support for asynchronous chaining via then(), exception handling with catch(), and result resolution using await().
• High-Performance IPC: Uses stream_socket_pair for parent-child communication with a custom binary protocol (Header + Payload) to ensure data integrity.
• Simple Facade: Unified entry point via Async::cpu() and Async::http().

📦 Installation

Ensure you have ext-pcntl, ext-posix, and ext-curl installed.

composer require happyslucker/a-async

🚀 Quick Start

1. CPU-Bound Parallelism

Run heavy tasks in the background without blocking the main process. PHP

use HappySlucker\AAsync\Async;

// Run a heavy task in a separate process
$future = Async::cpu()->run(function(int $times): int {
    $result = 0;
    for ($i = 0; $i < $times; $i++) { $result += $i; }
    return $result;
}, 1000000);

// Do something else here...

// Get the result (blocks until finished)
echo "Result: " . $future->await();

2. Concurrent Map (Parallel Processing)

Process a collection of items in parallel with a concurrency limit.

use HappySlucker\AAsync\Async;

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

$results = Async::cpu()->parallel(
    static fn(int $item): int => $item * 10,
    $items, 
    concurrency: 3
);

print_r($results);

3. Asynchronous HTTP (Fibers)

Perform non-blocking HTTP requests. The execution yields back to the manager while waiting for the network.

use HappySlucker\AAsync\Async;

$http = Async::http();

// Start multiple requests
$f1 = $http->get('https://httpbin.org/get');
$f2 = $http->get('https://httpbin.org/delay/1');

// Await them - the FiberManager handles the concurrent execution automatically
$res1 = $f1->await();
$res2 = $f2->await();


echo $res1->statusCode;

🛠️ Advanced Architecture

The Future Pattern

Both CPU and HTTP tasks return a Future object. You can handle results via blocking await() or non-blocking then().

use HappySlucker\AAsync\Async;

function foo(): int
{
    return 5 + 5;
}

$future = Async::cpu()
    ->run(static fn(): int => foo())
    ->then(static fn(int $result): int => $result * 5);

print_r($future->await());

Process Pool & Reaping

The ProcessPool automatically manages the lifecycle of child processes. It limits the number of active workers and "reaps" (cleans up) finished processes to prevent zombies and memory leaks.

Communication Channel

AAsync uses a binary header protocol over Unix Sockets for parent-child communication:

• Serialization: Uses MsgPack (if available) for speed, falling back to JSON.
• Transport: stream_socket_pair provides a bi-directional pipe.

⚙️ Requirements

• PHP: 8.3 or higher
• Extensions:
  • pcntl: Required for process forking.
  • posix: Required for process management.
  • curl: Required for async HTTP.
  • OS: Linux or macOS (Windows is not supported due to pcntl).

📜 License

The MIT License (MIT).

Created by HappySlucker. Happy coding! 🍻