Parallel Laravel Package

Getting Started

Start by installing the package via Composer: composer require amphp/parallel. Then identify blocking operations in your application (e.g., heavy I/O, CPU-bound tasks, or sequential database calls) that would benefit from parallelization. The first use case is typically offloading blocking I/O — like fetching many URLs — without halting your main event loop. Begin with Worker::submit() using a simple Task class implementing Task::run(), returning scalar or serializable data. Check the examples/ directory in the repo for ready-to-run samples (e.g., examples/parallel-http.php).

Implementation Patterns

• Task-based workers: Define reusable Task classes (e.g., EmailSenderTask, ImageResizeTask) with immutably typed constructors — avoid closures or non-serializable state to ensure proper serialize()/unserialize() across process boundaries.
• Worker pools for concurrency: Use WorkerPool (or the global pool via workerPool()) to concurrently execute tasks across multiple processes/threads. For CPU-bound work, tune pool size to core count; for I/O-bound, larger pools may be beneficial.
• IPC with channels: For long-running daemons or real-time bidirectional communication, use ContextFactory + Channel to exchange structured messages (e.g., AppMessage DTOs) between parent and child. Wrap messages in a sealed union type or enum for robust handling.
• Shared cache pattern: Use a static cache (e.g., LocalCache or AtomicCache) initialized inside Task::run() to persist state per worker (not across workers), ideal for caching database results or computed values across multiple tasks in the same worker.
• Cancellation-aware tasks: Accept the Cancellation argument in run() and periodically call $cancellation->throwIfRequested() or check $cancellation->isRequested() — especially important for long-running loops or async I/O inside tasks.

Gotchas and Tips

• Serialization boundaries: Only pass serializable data (scalar, arrays, Serializable, __sleep/__wakeup classes). Objects referenced in tasks must be autoloadable in both parent and worker — verify Composer’s autoload configuration (especially classmap or files) is available to worker processes.
• ZTS vs processes: Without ext-parallel and ZTS PHP 8.2+, the library falls back to proc_open child processes — slower startup, but more predictable isolation. Prefer threads if using CLI SAPI with php-zts.
• Avoid shared resources: Never attempt to send resources (e.g., PDO, file handles) over Channel. Reopen connections inside the child context.
• Cancellation is advisory: If a task ignores cancellation and completes, its result is still returned — always check $cancellation and handle Amp\Parallel\Worker\CancelledException where appropriate.
• Debugging tip: Use Amp\parallel\workerPool() to inject a custom pool in tests (e.g., with a mock ContextFactory) to avoid spawning real processes during unit tests.
• Performance: Workers are reused — but heavy memory leaks in tasks permanently leak memory in the worker process. Use gc_collect_cycles() or periodic worker recycling (via WorkerPool configuration or manual restarts) if necessary.