Download the PHP package hiblaphp/parallel without Composer

On this page you can find all versions of the php package hiblaphp/parallel. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package parallel

Hibla Parallel

The high-performance, self-healing, and cross-platform parallel processing engine for PHP.

Hibla Parallel brings Erlang-style reliability and Node.js-level cluster pool performance to the PHP ecosystem. You can orchestrate worker clusters that are fast (proven 100,000+ RPS on HTTP socket server benchmarks), truly non-blocking on all platforms, and capable of healing themselves through a supervised "Let it Crash" architecture.

Latest Release Windows Tests Linux Tests macOS Tests Total Downloads


Contents

Getting started

Project setup

Core concepts

Writing tasks

Persistent pools

Self-healing & supervision

Real-time communication

Advanced patterns

Error handling & safety

Reference

Meta


Installation

This package is currently in beta. Before installing, ensure your composer.json allows beta releases:

Requirements:


Quick Start

The fastest way to run code in a separate process and get the result back:

That is the entire API for the common case. The rest of this document covers everything built on top of it.


Global Configuration

Create a hibla_parallel.php in your project root to set system-wide defaults. Every value can be overridden per-task or per-pool using the fluent API.

The quickest way to get started is to copy the pre-commented config file directly from the package:

Then open the file and adjust the values for your environment. Alternatively, create it from scratch:


Autoloading & Code Availability

Hibla workers run in isolated PHP processes with a clean slate. Any code you want to execute in a worker must be available to that process.

Use namespaces and autoloading

The most reliable approach is to manage all classes and functions through Composer's autoloader:

Named functions vs. closures

Named functions (string callables like 'App\Tasks\myFunction') must exist in the worker via the autoloader or a bootstrap file. Closures are serialized by Hibla and transmitted to the worker. No autoloading is needed for the closure code itself, but any classes or functions called inside it must still be available:

Manual bootstrapping for legacy code

For legacy functions or global state that lives outside Composer's autoloader:


Framework Bootstrapping

Load Laravel, Symfony, or any custom environment inside your workers:

You can also set a system-wide default bootstrap so every task uses it automatically. See Global Configuration.


How Parallel Works

PHP is a single-threaded runtime. The event loop and fiber-based concurrency in hiblaphp/async let you interleave non-blocking I/O efficiently, but they do not escape this constraint: one thread, one CPU core. When you need to run genuinely CPU-bound work, call a blocking library that cannot be made async, or isolate a task so a fatal error in it cannot kill your main process, you need true parallelism.

There are two common approaches to parallelism in PHP: multi-threading and multi-processing. Multi-threading solutions such as the parallel extension use native threads implemented as a C extension. Rather than relying on shared mutable memory directly, parallel primarily uses channels and isolated runtimes for communication, which helps reduce traditional race-condition issues. However, it remains a relatively niche solution in the PHP ecosystem and is not widely adopted compared to process-based parallel models. Hibla Parallel currently does not use this model.

Multi-processing spawns independent OS processes that share nothing and communicate explicitly. It is simpler to reason about, safer by default, and available in every PHP environment without extensions. This is the model Hibla Parallel is built on. Multi-threading support is not currently planned.

Hibla Parallel solves this by spawning real child processes via proc_open() and communicating with them over OS-level I/O channels. Each worker is a fresh PHP process with its own memory space, its own CPU scheduling, and its own crash domain. A segfault, out-of-memory kill, or unhandled fatal in a worker cannot corrupt or terminate the parent.

When you call parallel(fn() => heavyWork()):

  1. Spawn. The parent calls proc_open() to start a new PHP process running one of Hibla's worker scripts. The worker receives its I/O channels (stdin, stdout, stderr) at the OS level.
  2. Serialize. The parent serializes the closure (its code, bound variables, and $this if captured) into a JSON payload and writes it to the worker's stdin.
  3. Execute. The worker reads the payload, deserializes the closure, runs it inside its own event loop, and captures the return value.
  4. Communicate. The worker writes structured JSON frames back to the parent over stdout in real time: output frames as the task runs, a terminal frame when it finishes.
  5. Deserialize. The parent reads the terminal frame, deserializes the result, and resolves the promise.

The parent never blocks during this. Communication happens over non-blocking streams managed by hiblaphp/stream, so the parent's event loop continues running other fibers, timers, and I/O while it waits for a worker to finish. A pool of four workers can handle four tasks simultaneously without the parent event loop stalling at all.


Worker Types

Hibla Parallel ships three worker scripts, each optimized for a different execution model. The parent selects the correct script automatically based on which API you use.

Streamed worker (worker.php)

Used by parallel() and Parallel::task(). Spawned fresh for each task. Maintains full bidirectional communication with the parent: OUTPUT frames stream in real time, emit() sends MESSAGE frames, exceptions teleport back as ERROR frames, and results are transmitted as COMPLETED frames. The worker exits after handling one task.

Background worker (worker_background.php)

Used by spawn() and Parallel::background(). Spawned fresh for each task. stdout and stderr are redirected to /dev/null at spawn time, so the parent has no communication channel back from this worker. The worker runs the task and exits. This means emit() is a silent no-op inside background workers, and there is no result, no exception teleportation, and no real-time output. Use this only for true fire-and-forget work where you do not need to know what happened inside.

Persistent worker (worker_persistent.php)

Used by Parallel::pool(). Spawned once per pool slot at pool construction (or on first use with lazy spawning) and kept alive to handle many tasks sequentially. Shares the same structured-frame communication protocol as the streamed worker but with task IDs added to every frame for routing, plus the READY/RETIRING/CRASHED lifecycle frames. Crashes trigger the pool's respawn logic. Retirement after withMaxExecutionsPerWorker(n) tasks triggers a clean RETIRING exit and an automatic replacement.


Serialization: Crossing the Process Boundary

The central challenge in any multi-process system is that processes do not share memory. Everything that moves between the parent and a worker (the task to run, the result it produces, exceptions it throws, and messages it emits) must be converted to bytes, transmitted, and reconstructed on the other side.

Serializing the task

PHP closures are not natively serializable. Hibla uses opis/closure to serialize the AST (Abstract Syntax Tree) of the closure's source code along with any variables it captures from its surrounding scope. The serialized representation is a compact string that the worker can deserialize back into a fully functional callable, including bound variables and the captured $this object if the closure was defined inside a class method.

The entire task payload is JSON-encoded before being written to the worker's stdin:

Serializing the result

Once the task finishes, the worker serializes the return value back to the parent. Scalar values (strings, integers, floats, booleans, null) and plain arrays are JSON-encoded directly. Objects and nested arrays containing objects are serialized with PHP's native serialize() and base64-encoded before being embedded in the JSON frame:

The parent checks the result_serialized flag, decodes and unserializes the value if needed, and resolves the promise with the reconstructed object. The object arrives in the parent with its type, properties, and values intact, as if it had never left the process.

Serializing exceptions

When a task throws, the worker captures the exception's class name, message, code, file, line, and full stack trace, encodes them as a structured ERROR frame, and sends it to the parent. The parent's ExceptionHandler re-instantiates the original exception class (falling back to RuntimeException if the class is not available in the parent) and merges the worker's stack trace into it, so the combined trace shows both where parallel() was called in the parent and where the exception was thrown in the worker.

What cannot be serialized

Objects that hold active OS resources (open database connections, PDO handles, open file pointers, network sockets, cURL handles) cannot be serialized because the resource itself lives in the OS kernel and is tied to the specific process that opened it. Attempting to pass one will fail at serialization time with a TaskPayloadException.

The pattern for these cases is to initialize the resource inside the worker, not pass it in:


IPC: Inter-Process Communication

Hibla Parallel communicates with workers over OS-level I/O channels created by proc_open(). Understanding this channel design explains why the library is non-blocking even on Windows and how real-time output streaming works.

Structured frames

All communication uses a simple line-delimited JSON protocol, similar in spirit to NDJSON and JSON Lines, but implemented directly over proc_open() pipes rather than files or TCP sockets. The parent writes one JSON line to the worker's stdin to deliver the task. The worker writes JSON lines to its stdout as the task runs. Each line is a complete, self-contained JSON object terminated by a newline. The parent reads lines one at a time on a non-blocking stream and routes each frame by its status field.

Frame type Direction When it is sent
OUTPUT Worker to Parent The task called echo or print
MESSAGE Worker to Parent The task called emit()
COMPLETED Worker to Parent The task returned a value
ERROR Worker to Parent The task threw an exception
TIMEOUT Worker to Parent The task exceeded its time limit
READY Worker to Parent Persistent workers only: worker booted and is ready for a task
RETIRING Worker to Parent Persistent workers only: worker has hit its max executions limit and is exiting cleanly
CRASHED Worker to Parent Persistent workers only: worker is dying due to an unrecoverable error

Pipes on Unix, sockets on Windows

On Linux and macOS, Hibla uses anonymous pipes (['pipe', 'r'] and ['pipe', 'w'] in the proc_open() descriptor spec). Anonymous pipes support stream_set_blocking(false) correctly at the kernel level, making them fully compatible with the non-blocking stream layer. They are also approximately 15% faster than sockets for small messages.

On Windows, anonymous pipes do not support non-blocking mode at the kernel level. Calling stream_set_blocking($pipe, false) on a Windows anonymous pipe is silently ignored and the pipe remains blocking. A blocking read on a pipe that has no data stalls the entire PHP thread indefinitely, which would deadlock the event loop.

Hibla detects the platform at spawn time and switches to socket pairs (['socket']) on Windows. Socket pairs support true non-blocking mode on Windows and are the standard solution for this limitation. The rest of the code (stream reading, frame parsing, promise resolution) is identical on both platforms:

Stdin handshake and drain-and-wait

After the worker finishes and writes its terminal frame (COMPLETED, ERROR, or TIMEOUT), it does not exit immediately. On Windows, a process exiting instantly destroys its socket descriptors, which can wipe out bytes that are still in the OS transmit buffer before the parent's non-blocking stream reader has consumed them.

To prevent this, the worker enters a drain-and-wait loop after writing the terminal frame: it switches its own stdin to non-blocking mode and reads in a 5ms polling loop for up to 500ms. The parent signals it is done by closing its end of the stdin pipe after receiving the terminal frame, which causes feof() to return true in the worker's drain loop and lets the worker exit cleanly. This handshake guarantees the terminal frame is always fully received before the worker process disappears.

Persistent worker IPC

Persistent pool workers use the same channel design but stay alive across multiple tasks. Instead of a one-shot payload-and-exit model, the boot sequence works like this:

  1. The parent spawns the worker and writes a one-time boot payload to stdin with the autoload path, bootstrap configuration, memory limit, and retirement threshold.
  2. The worker loads the autoloader, runs any framework bootstrap, and writes {"status":"READY","pid":12345} to stdout.
  3. The parent dispatches queued tasks by writing JSON lines to stdin, one per task, each identified by a unique task_id.
  4. The worker reads task lines in a loop, executes each one, and writes COMPLETED or ERROR frames tagged with the same task_id back to stdout.
  5. All frames from all tasks share the same stdout channel. The task_id tag allows the parent to route each frame to the correct task's promise and onMessage handler.

The worker reports its own PID (getmypid()) in the READY frame because proc_get_status()['pid'] returns the shell wrapper's PID on some platforms rather than the actual PHP process PID. The self-reported PID is used for SIGKILL / taskkill on cancellation and is what getWorkerPids() returns once the READY frame has been received. See Pool Monitoring for the full detail on PID accuracy.


Simple Primitives

Hibla provides global helper functions for the most common use cases.

One-off tasks with results

Fire-and-forget


Rich Data & Stateful Execution

Hibla Parallel is not limited to scalar return values. Because it uses a full serialization engine, you can pass objects into tasks, return objects from tasks, and access class state from inside parallel closures. All of it crosses the process boundary transparently.

Returning value objects

Any serializable object returned from a worker is reconstructed in the parent with its type, class name, and property values intact:

Accessing class properties ($this)

When parallel() is called inside a class method, the closure can capture $this. The worker receives a serialized copy of the object and can read its properties, including private ones:

Two rules for object serialization

  1. Autoloading. The class definition must be available to the worker via the Composer autoloader or a bootstrap file. If the worker cannot find the class, deserialization will fail.
  2. No resources. Objects holding active OS resources (PDO handles, open file pointers, network sockets) cannot cross the process boundary. See Serialization: Crossing the Process Boundary for the correct pattern.

Global Helper Functions

Hibla Parallel exposes four global helpers in the Hibla namespace. They are thin wrappers around the facade and are the recommended API for most scripts. All four accept an optional $timeout argument. For anything beyond a simple timeout override (custom memory limits, bootstrap files, or message handlers) use the fluent executors directly (see Using runFn and spawnFn on fluent executors).

parallel(callable $task, ?int $timeout = null)

Runs a task in a new process and returns a Promise resolving to the task's return value.

parallelFn(callable $task, ?int $timeout = null)

Wraps a callable and returns a new callable that spawns a fresh parallel process on each invocation. Useful with higher-order functions like Promise::all() or event listeners where you need to pass a callable rather than invoke one immediately.

spawn(callable $task, ?int $timeout = null)

Spawns a fire-and-forget background process. The returned Promise resolves immediately with a BackgroundProcess handle. No result, output, or exception is ever returned to the parent.

spawnFn(callable $task, ?int $timeout = null)

The fire-and-forget equivalent of parallelFn. Returns a callable that spawns a new detached background process on each invocation.

Note: emit() called inside a spawn() or spawnFn() task is a silent no-op. Fire-and-forget workers redirect stdout to /dev/null, so structured message passing is unavailable. Use parallel() or a pool if you need emit().

Using runFn and spawnFn on fluent executors

The global helpers use default configuration. When you need custom timeouts, memory limits, a bootstrap file, or message handlers applied consistently to every invocation of the factory, use the ->runFn() and ->spawnFn() methods on the fluent executors instead.

The returned callable behaves identically to calling ->run() or ->spawn() directly. The only difference is that you get a reusable callable rather than an immediate promise.

Parallel::task()->runFn()

Each invocation spawns a fresh worker with the configured settings:

runFn() accepts a per-invocation message handler as its second argument. It fires before the executor-level onMessage handler, following the same ordering rules described in Pool-Level vs. Per-Task Message Handlers:

Parallel::pool()->runFn()

Tasks are dispatched to the pool's persistent workers rather than spawning a fresh process per invocation. Use this when you want both the reuse efficiency of a pool and a consistent callable interface for higher-order functions:

Parallel::background()->spawnFn()

Each invocation spawns a detached fire-and-forget process with the configured settings. The returned promise resolves immediately with a BackgroundProcess handle, not a task result:

Note: emit() called inside a ->spawnFn() task is a silent no-op. Fire-and-forget workers redirect stdout to /dev/null, so structured message passing is unavailable. Use ->runFn() or a pool if you need emit().

Choosing between global helpers and fluent factories

Use parallelFn() and spawnFn() for quick scripts where the defaults are acceptable. Use ->runFn() and ->spawnFn() on the fluent executors whenever you need consistent configuration, message handlers, or bootstrap logic applied to every invocation, or when working with a pool and want to avoid constructing a new executor on each call.


Quick Reference

Choose the right tool for your use case:

Use Case API Returns
Run a task and get its result parallel(fn() => ...) or Parallel::task()->run(...) PromiseInterface<TResult>
Run many tasks, wrapping a callable parallelFn(callable) or Parallel::task()->runFn(callable) callable(mixed ...$args): PromiseInterface<TResult>
Fire-and-forget background work spawn(fn() => ...) or Parallel::background()->spawn(...) PromiseInterface<BackgroundProcess>
Fire-and-forget, wrapping a callable spawnFn(callable) or Parallel::background()->spawnFn(callable) callable(mixed ...$args): PromiseInterface<BackgroundProcess>
High-throughput repeated work Parallel::pool(n)->run(...) PromiseInterface<TResult>
High-throughput, wrapping a callable Parallel::pool(n)->runFn(callable) callable(mixed ...$args): PromiseInterface<TResult>

Fluent configuration is available on all strategies:

Method Effect
->withTimeout(int $seconds) Reject with TimeoutException after N seconds, terminate the worker and its full process tree
->withoutTimeout() Disable the timeout entirely
->withMemoryLimit(string $limit) Set worker memory limit (e.g. '256M', '1G')
->withUnlimitedMemory() Set memory limit to -1
->withBootstrap(string $file, ?callable $cb) Load a framework or legacy environment in the worker
->withMaxNestingLevel(int $level) Override the fork-bomb safety limit (1-10)
->withLazySpawning() Pool only: spawn workers on first run() call instead of at construction
->withMaxExecutionsPerWorker(int $n) Pool only: retire and replace workers after N tasks
->withMaxRestartPerSecond(int $n) Pool only: limit respawn rate to N workers per second
->onMessage(callable $handler) Task/Pool: register a handler for emit() messages from workers
->onWorkerRespawn(callable $handler) Pool only: called whenever a worker exits and a replacement is spawned
->boot() Pool only: pre-warm all workers immediately; returns before workers are ready

Persistent Worker Pools

Worker pools maintain a fixed set of long-lived workers to eliminate the overhead of repeated process spawning and framework bootstrapping. Each worker handles multiple tasks sequentially, making pools ideal for high-throughput workloads.

Explicit Lifecycle Management

While Hibla Parallel automatically cleans up idle pools when your script ends, you may still want to shut down pools manually in long-running daemons (like web servers) to free up OS resources immediately when a pool is no longer needed.

Automatic garbage collection between tasks

After every completed task, before writing the next READY frame, each persistent worker automatically calls gc_collect_cycles() to collect any reference cycles left behind by the task. This runs unconditionally regardless of any other configuration and provides a baseline level of memory hygiene at no cost to the caller.

For most workloads this is sufficient. If a task leaves behind significant heap allocations, large static caches, or framework state that the garbage collector cannot reclaim, use withMaxExecutionsPerWorker() to retire and replace workers at a predictable cadence.

Why withMaxExecutionsPerWorker?

Long-running pools can accumulate memory over time even with cycle collection in place. PHP's OPcache grows, framework static caches fill up, and residual heap allocations may persist across tasks. By retiring a worker after N tasks and replacing it with a fresh process, you get a fully clean memory slate at a predictable cadence. This matters most for pools that run for hours or days.

Lazy vs. Eager Spawning

By default, pools use eager spawning: all workers are spawned together when the pool manager is initialized. However, the pool manager itself is initialized lazily on the first run() call. This means even with eager spawning (the default), the first task submitted to the pool will incur the full cost of booting every worker process unless boot() is called explicitly beforehand.

Pre-warming with boot()

The boot() method pre-warms the pool and guarantees that every worker is genuinely ready to accept tasks before it returns. It is context-aware: if called inside an async fiber, it suspends the fiber without blocking the event loop; if called in a synchronous script, it blocks execution and pumps the event loop until the pool is ready.

Once boot() returns:

Synchronous usage:

Asynchronous usage:

Lazy Spawning

Use lazy spawning when the pool is conditional or short-lived and workers may never be needed. Workers are spawned one-by-one only as tasks are submitted.

Calling boot() on a lazy pool forces the manager to initialize, but workers still spawn individually on each run() call. For lazy pools, boot() returns immediately since there is no pre-boot phase.

The trade-off: The first batch of tasks will incur worker boot latency (roughly 50-100ms per worker), and bootstrap errors (like syntax errors in your bootstrap file) will surface during task submission rather than during pool setup.


Self-Healing & Supervisor Pattern

You can build Erlang-style supervised clusters with Hibla Parallel. If a worker crashes for any reason (segfault, out-of-memory kill, or an explicit exit()) Hibla detects the death, immediately spawns a replacement worker to maintain pool capacity, and fires the onWorkerRespawn hook so you can re-submit whatever that worker was doing.

onWorkerRespawn fires on both crashes and planned retirements.

When a worker reaches its withMaxExecutionsPerWorker() limit it exits cleanly with a RETIRING frame rather than a crash signal, but the pool treats both events identically from the caller's perspective: a replacement worker is spawned and onWorkerRespawn is called. This means any long-running task that was running on a retiring worker needs to be re-submitted in the hook just as it would after a crash. If you use withMaxExecutionsPerWorker() without an onWorkerRespawn handler, long-running tasks submitted to that worker will not be re-submitted on retirement.

The pattern is three lines:

Complete example: chaos server

The following example makes the supervisor behavior directly observable. Each worker binds to port 8080 via SO_REUSEPORT and serves HTTP requests. The /crash route lets you trigger a controlled worker crash from the browser and watch the master detect and recover from it in the terminal in real time.

Run it with php chaos_server.php and visit http://127.0.0.1:8080/crash in a browser to trigger a crash. The terminal output shows the full lifecycle:

Three things to notice in this output:

The master PID never changes. 6309 supervises the entire session and is not affected by any worker crash or retirement.

Every exit is followed immediately by a new worker PID coming online. The pool never drops below 4 listening workers. From the perspective of any HTTP client hitting port 8080, the cluster is healthy throughout.

You can hit /crash as many times as you like. The cluster recovers every time with no manual intervention and no restart of the master process.


Respawn Rate Limiting

By default, the pool will respawn a crashed worker immediately and without limit. This is the right behavior for isolated, one-off crashes: a bad task payload, a transient fault, or a single worker OOM kill. The replacement is up and running before the next task even notices.

However, if the root cause is not transient (a broken bootstrap file, a fatal error in every task, or an unserializable payload submitted in a loop) every replacement worker will crash for the exact same reason. Without a circuit breaker, the pool enters an uncontrolled crash loop, spawning, crashing, and re-spawning at full speed until either the OS runs out of resources or the process table fills up.

withMaxRestartPerSecond() is that circuit breaker. It counts worker respawns in a one-second sliding window and shuts the pool down with a RespawnRateLimitException the moment the threshold is crossed:

Fail-fast, not slow-fail

When the limit is exceeded, the pool does not pause and retry. It shuts down immediately and rejects every pending promise. This is intentional.

A rapid crash loop is almost never a transient problem. The 5th respawn will fail for the exact same reason as the 1st. Slowing down the respawn rate with backoff just delays the inevitable while leaving the task queue growing with unprocessed work and giving callers false hope that the pool is still functional. Failing fast means every caller is notified immediately via a rejected promise, no resources are wasted on doomed respawns, and the root cause surfaces sooner rather than being obscured by retry noise.

Choosing the right limit

The library does not set a default. Your workload determines what "too many restarts" looks like, and a wrong default is worse than no default. Too tight and you kill a healthy pool; too loose and the protection is meaningless.

Use these factors to guide your choice:

Factor Consideration
Pool size A pool of 8 workers retiring via withMaxExecutionsPerWorker will naturally respawn more often than a pool of 2. Account for planned retirements.
Task duration Short tasks cycle workers faster. A limit that works for 10-second tasks may be too tight for 50ms tasks with high throughput.
Expected crash rate If occasional worker crashes are normal for your workload, set the limit above your expected noise floor.
Environment stability Development environments with frequent code changes crash more often than production. Consider separate configs.

A reasonable starting point for most production pools is 3 to 5. This comfortably absorbs occasional one-off crashes while still catching a true crash loop within a second.

Interaction with onWorkerRespawn

onWorkerRespawn fires on every successful respawn, including the ones counted toward the rate limit. Once the limit is exceeded and the pool shuts down, the hook will no longer fire. Design your respawn handler accordingly: do not assume it will always be called, and do not use it as the sole mechanism for detecting a crash loop.

Note: withMaxRestartPerSecond is opt-in and null by default. If you do not set it, the pool will respawn crashed workers indefinitely with no rate check. For any long-running pool in production, setting an explicit limit is strongly recommended.


Pool Monitoring

You can inspect a live pool to understand its current state. This is useful for health checks, dashboards, and debugging.

PID accuracy and boot()

getWorkerPids() returns the real PHP process PIDs as self-reported by each worker in its READY frame. These match exactly what getmypid() returns inside a running task on every platform, including Windows.

Because workers go through a shell wrapper phase before the PHP binary fully initializes, calling getWorkerPids() immediately after constructing a pool may return temporary PIDs.

To guarantee PID accuracy for monitoring or health checks, always call boot() first. Because boot() waits for every worker to signal readiness, the PIDs are guaranteed to be authoritative the moment the method returns:


Real-time Output & Messaging

Console Streaming

Everything printed inside a worker using echo, print, or any function that writes through PHP's output buffer is captured and streamed to the parent console in real time via non-blocking frames:

Direct writes to STDOUT are not captured.

Hibla intercepts output by installing an output buffer handler (ob_start) inside the worker. That handler only captures what flows through PHP's output buffering layer: echo, print, printf, var_dump, print_r, and similar functions all go through it. Calls that bypass the buffer and write directly to the file descriptor (fwrite(STDOUT, ...), fputs(STDOUT, ...)) are not intercepted and will not reach the parent.

If you need to send structured data back to the parent rather than raw console output, use emit() with an onMessage handler instead:

See Structured Messaging with emit() for the full messaging API.

Structured Messaging with emit()

Use emit() to send structured data back to the parent without finishing the task. The parent receives a WorkerMessage object with $msg->data containing the emitted value and $msg->pid containing the worker's process ID.

emit() supports any serializable PHP value: scalars, arrays, and objects all cross the process boundary transparently. This means you can emit typed value objects and use instanceof checks in your onMessage handler to branch on message type, giving you a clean and expressive messaging protocol without string-based type flags:

For this to work, the message classes must be autoloaded in both the worker and the parent. Define them in your application's namespace and let Composer handle the rest.

Note: Calling emit() inside a fire-and-forget worker spawned via spawn() or spawnFn() is a silent no-op. Those workers redirect stdout to /dev/null, so message passing is unavailable. Use parallel() or a pool if you need emit().

Pool-Level vs. Per-Task Message Handlers

You can register message handlers at two levels. The pool-level handler always starts first. It is launched before the per-task handler and begins executing immediately. Both then run concurrently as async fibers, interleaving at any await point, so the total wall-clock cost equals the slowest handler rather than the sum:

The same two-level composition is available on Parallel::task() using ->onMessage() for the executor level and the second argument to ->run() for the per-task level.

Concurrent handlers and shared state

Because handlers run concurrently as fibers, handlers that share mutable state can race at any await point. Independent handlers (logging, metrics, tracing) are unaffected and need no guards. But if two handlers both read and write the same variable, one can read a stale value before the other has written back:

Protect the critical section with a Mutex from hiblaphp/sync:

Handlers that do not share state need no guards. The concurrency is free.

Handler completion blocks task promise resolution

The parent does not resolve the task promise (and therefore does not return from await(parallel(...))) until every registered onMessage handler has finished executing. All handlers start concurrently as async fibers, so the total wall-clock cost equals the slowest handler, not the sum of all handlers. But if any single handler does slow I/O, a blocking database write, or a long-running computation, it delays the parent receiving the task result even if the worker itself finished long ago.

Keep onMessage handlers fast. If you need to do slow work in response to a message (writing to a database, calling an external API) dispatch it as a background task from inside the handler rather than doing it inline:


Fractal Concurrency: The Async Hybrid

Hibla Parallel provides a unified concurrency model. While async/await handles non-blocking I/O, parallel() offloads actual blocking PHP functions (like sleep(), legacy database drivers, or CPU-heavy work) to separate processes.

This is not limited to the parallel() helper. Every execution strategy (Parallel::task(), Parallel::pool(), Parallel::background(), and their runFn/spawnFn factory variants) participates in the same model. You can freely mix pool tasks, one-off tasks, background spawns, and fiber-based async work in a single Promise::all() and they all run concurrently, each contributing its result when ready.

Because every worker is a smart worker with its own event loop, you can also mix these models recursively up to the maximum process nesting limit. A worker can itself spawn further parallel tasks or run async fibers internally. The following block demonstrates this and finishes in exactly 1 second:

The event loop does not care whether a given unit of work is a process-backed promise from a pool worker or a fiber-backed promise from async(). It drives all of them forward concurrently on the same tick cycle. The result is a single composable concurrency model rather than two separate systems you have to coordinate manually.


Nested Execution & Safety

Workers are real OS processes and each one can itself call parallel(), spawn(), or any Parallel:: executor to spawn further child processes. Hibla enforces a configurable nesting limit (default 5) to prevent runaway recursive spawning from exhausting system resources. Cancellation propagates through the full tree. Cancelling a parent worker also terminates all nested workers it spawned, at any depth, on both Linux and Windows.

The nested closure problem

Hibla serializes closures using opis/closure, which locates a closure by its line number in the source file. When two parallel() calls share the same source line, the serializer extracts the outer closure instead of the inner one. The child worker deserializes and runs the outer call, spawning another outer process, which does the same thing again indefinitely. This is a fork bomb.

Beyond the fork bomb risk, short closures (fn() => ...) implicitly capture the entire parent scope by value. In a large application this can silently serialize megabytes of unintended data into the task payload.

Hibla automatically detects the most dangerous patterns and throws a NestingLimitException before any process is spawned. The examples below show what to avoid and what to use instead, ordered from most dangerous to safest.

Closure safety levels

DANGEROUS: single-line nested short closures

The serializer sees one line, extracts the outer closure, and the worker re-spawns the outer call infinitely:

RISKY: multi-line nested short closures

Splitting across lines avoids AST corruption, but fn() still captures the entire parent scope. Auto-formatters (Pint, PHP-CS-Fixer) may also collapse multi-line short closures back to one line on the next run:

SAFER: regular closures with explicit use

Only the variables you name are serialized. Nothing implicit, nothing surprising:

SAFEST: non-closure callables (recommended for all nested tasks)

Nothing to serialize beyond the class or function name. No AST parsing, no scope capture. Classes and functions must be available via Composer autoloading:

Always await() nested calls

Always await() the result of a nested parallel() or spawn() call inside a worker. An un-awaited nested task may be killed by the OS if the parent worker exits first, and nesting limit enforcement depends on the promise being tracked.

Configuring the nesting limit

The default of 5 is sufficient for virtually all real workloads. If you genuinely need deeper nesting, raise it per-executor or globally in config. The hard ceiling is 10:


Distributed Exception Teleportation

Hibla Parallel teleports exceptions from workers back to the parent. It re-instantiates the original exception type and merges stack traces so you see exactly where the error originated:


Abnormal Termination Detection

If a worker hits a segmentation fault, runs out of memory, or calls exit(), Hibla Parallel detects the silent death and rejects the promise with a ProcessCrashedException:


Task Cancellation & Management

Cancelling a task promise forcefully kills the underlying OS process and its entire descendant tree, including any nested parallel() workers spawned inside the cancelled worker. For pools, a fresh replacement worker is immediately respawned to maintain capacity.

Full process tree cancellation

Cancellation is not limited to the direct worker. If a worker itself spawned nested parallel() calls (which is fully supported up to max_nesting_level) all of those child and grandchild processes are terminated together with their parent. No orphaned workers survive a cancel.

This matters because a cancellation API that does not propagate to descendants is not a real cancellation. The work continues in orphaned background processes with no owner, no handle, and no way to stop them. Hibla treats full tree kill as non-negotiable.

Cancellation in a pool kills the entire worker, not just the task

When you cancel a task promise, Hibla Parallel terminates the entire worker process for that slot, not just the in-flight task. The cancelled task is killed immediately and the worker process is torn down along with any nested children it spawned. A fresh replacement worker is spawned to restore pool capacity, and any tasks still waiting in the pool's global queue are dispatched to workers as normal. They are not affected by the cancellation.

The distinction matters for one specific case: if the cancelled task was mid-execution and the worker held any state that other code depended on, that state is gone with the process. The cancellation blast radius is one worker slot, its single in-flight task, and any nested workers that task had spawned. Nothing wider.

For one-off tasks spawned via Parallel::task(), cancellation only kills that single worker tree and has no wider effect.


Exception Reference

All exceptions extend Hibla\Parallel\Exceptions\ParallelException, which extends \RuntimeException. Catch the base class to handle any Hibla-specific error generically, or catch specific types for granular handling.

Exception Class When it is thrown
ProcessCrashedException A worker exits unexpectedly (segfault, exit(), OOM kill, stream EOF)
TimeoutException A task exceeds its configured timeout
NestingLimitException A parallel() call would exceed max_nesting_level
RateLimitException More than spawn_limit_per_second background tasks are spawned in one second
PoolShutdownException A task is submitted to (or was queued in) a pool that has been shut down
TaskPayloadException The task callback cannot be serialized, or the JSON payload encoding fails
ProcessSpawnException The OS fails to spawn a new process, or required functions are disabled in php.ini
RespawnRateLimitException More than max_restart_per_second workers are respawned in one second

System Utilities

Hibla\Parallel\Utilities\SystemUtilities is a static utility class that provides cross-platform helpers for process management and environment inspection. Most of its methods are used internally by the library, but several are useful directly in application code.

getCpuCount()

Returns the number of logical CPU cores available on the current machine. The result is cached after the first call, since the CPU count does not change during a process's lifetime.

The primary use case is sizing a worker pool to match the hardware it runs on, so you get maximum parallelism without over-subscribing the CPU scheduler:

Detection strategy (in priority order)

The method uses platform-specific commands to query the OS and falls back progressively if a step fails:

Platform Primary source Fallback
Linux nproc via shell_exec /sys/devices/system/cpu/present, then /proc/cpuinfo
macOS sysctl -n hw.logicalcpu via shell_exec None
Windows wmic cpu get NumberOfLogicalProcessors via shell_exec NUMBER_OF_PROCESSORS environment variable
Any None Returns 4 as a safe, conservative default

The method always returns at least 1 regardless of what the OS reports.

Note: This reports logical cores (hardware threads), not physical cores. On a machine with 4 physical cores and hyperthreading enabled, getCpuCount() returns 8. For CPU-bound PHP workloads, using the physical core count is often more efficient because two hyperthreads share one execution unit. As a starting point, benchmark both getCpuCount() and getCpuCount() / 2 for your specific workload.

getPhpBinary()

Returns the absolute path to the PHP binary currently running the script. The result is cached after the first call.

Hibla uses this internally when spawning worker processes to guarantee that every worker runs the same PHP binary as the parent, regardless of what php resolves to on $PATH. Call it directly if you need the binary path for your own proc_open() or exec() calls and want the same guarantee.

validateEnvironment()

Checks that all required PHP functions are available in the current environment and throws EnvironmentException if any are disabled. Hibla calls this automatically on first use, so you will never reach parallel() with a broken environment. Call it yourself during application boot if you want to surface configuration problems at startup rather than at the point of first use:

Required functions are proc_open, exec, and shell_exec on all platforms, plus posix_kill on Linux and macOS. These are typically disabled on shared hosting environments. Hibla Parallel requires a VPS, a container, or a dedicated server where process management functions are available.


Architecture & Testability

Hibla Parallel is designed with testability in mind. The Parallel facade provides a clean entry point to three independent strategies, each backed by a dedicated interface and a concrete implementation.

Strategy Map

Facade Method Concrete Class Interface Description
Parallel::task() ParallelExecutor ParallelExecutorInterface One-off tasks that return a result. A fresh worker is spawned per run() call.
Parallel::pool(n) ProcessPool ProcessPoolInterface A managed cluster of reusable persistent workers.
Parallel::background() BackgroundExecutor BackgroundExecutorInterface Detached fire-and-forget processes. No result is returned.

Using the Facade (Recommended)

Direct Instantiation (Best for DI)

Dependency Injection & Mocking


Credits


License

MIT License. See LICENSE for more information.


All versions of parallel with dependencies

PHP Build Version
Package Version
Requires php Version ^8.4
rcalicdan/config-loader Version ^1.0
rcalicdan/serializer Version ^1.0
rcalicdan/process-killer Version ^1.0
hiblaphp/event-loop Version ^1.0
hiblaphp/promise Version ^1.0
hiblaphp/cancellation Version ^1.0
hiblaphp/async Version ^1.0
hiblaphp/stream Version ^1.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package hiblaphp/parallel contains the following files

Loading the files please wait ...