Download the PHP package amphp/parallel without Composer

amphp/parallel

AMPHP is a collection of event-driven libraries for PHP designed with fibers and concurrency in mind. amphp/parallel provides true parallel processing for PHP using multiple processes or threads, without blocking and no extensions required.

To be as flexible as possible, this library comes with a collection of non-blocking concurrency tools that can be used independently as needed, as well as an "opinionated" worker API that allows you to assign units of work to a pool of worker processes.

Requirements

• PHP 8.1+

Optional requirements to use threads instead of processes

• PHP 8.2+ ZTS
• ext-parallel

Installation

This package can be installed as a Composer dependency.

Usage

The basic usage of this library is to submit blocking tasks to be executed by a worker pool in order to avoid blocking the main event loop.

FetchTask is just used as an example for a blocking function here. If you just want to fetch multiple HTTP resources concurrently, it's better to use amphp/http-client, our non-blocking HTTP client.

Note The functions you call must be predefined or autoloadable by Composer, so they also exist in the worker process or thread.

Workers

Worker provides a simple interface for executing PHP code in parallel in a separate PHP process or thread. Classes implementing Task are used to define the code to be run in parallel.

Tasks

The Task interface has a single run() method that gets invoked in the worker to dispatch the work that needs to be done. The run() method can be written using blocking code since the code is executed in a separate process or thread.

Task instances are serialize'd in the main process and unserialize'd in the worker. That means that all data that is passed between the main process and a worker needs to be serializable.

In the example below, a Task is defined which calls a blocking function (file_get_contents() is only an example of a blocking function, use http-client for non-blocking HTTP requests).

Child processes or threads executing tasks may be reused to execute multiple tasks.

Sharing data between tasks

Tasks may wish to share data between tasks runs. A Cache instance stored in a static property that is only initialized within Task::run() is our recommended strategy to share data.

You may wish to provide a hook to initialize the cache with mock data for testing.

A worker may be executing multiple tasks, so consider using AtomicCache instead of LocalCache when creating or updating cache values if a task uses async I/O to generate a cache value. AtomicCache has methods which provide mutual exclusion based on a cache key.

Task cancellation

A Cancellation provided to Worker::submit() may be used to request cancellation of the task in the worker. When cancellation is requested in the parent, the Cancellation provided to Task::run() is cancelled. The task may choose to ignore this cancellation request or act accordingly and throw a CancelledException from Task::run(). If the cancellation request is ignored, the task may continue and return a value which will be returned to the parent as though cancellation had not been requested.

Worker Pools

The easiest way to use workers is through a worker pool. Worker pools can be used to submit tasks in the same way as a worker, but rather than using a single worker process, the pool uses multiple workers to execute tasks. This allows multiple tasks to be executed simultaneously.

The WorkerPool interface extends Worker, adding methods to get information about the pool or pull a single Worker instance out of the pool. A pool uses multiple Worker instances to execute Task instances.

If a set of tasks should be run within a single worker, use the WorkerPool::getWorker() method to pull a single worker from the pool. The worker is automatically returned to the pool when the instance returned is destroyed.

Global Worker Pool

A global worker pool is available and can be set using the function Amp\Parallel\Worker\workerPool(?WorkerPool $pool = null). Passing an instance of WorkerPool will set the global pool to the given instance. Invoking the function without an instance will return the current global instance.

Child Processes or Threads

Contexts simplify writing and running PHP in parallel. A script written to be run in parallel must return a callable that will be run in a child process or thread. The callable receives a single argument – an instance of Channel that can be used to send data between the parent and child processes or threads. Any serializable data can be sent across this channel. The Context object, which extends the Channel interface, is the other end of the communication channel.

Contexts are created using a ContextFactory. DefaultContextFactory will use the best available method of creating context, creating a thread if ext-parallel is installed or otherwise using a child process. ThreadContextFactory (requires a ZTS build of PHP 8.2+ and ext-parallel to create threads) and ProcessContextFactory are also provided should you wish to create a specific context type.

In the example below, a child process or thread is used to call a blocking function (file_get_contents() is only an example of a blocking function, use http-client for non-blocking HTTP requests). The result of that function is then sent back to the parent using the Channel object. The return value of the child callable is available using the Context::join() method.

Child Process or Thread

Parent Process

Child processes or threads are also great for CPU-intensive operations such as image manipulation or for running daemons that perform periodic tasks based on input from the parent.

Context creation

An execution context can be created using the function Amp\Parallel\Context\startContext(), which uses the global ContextFactory. The global factory is an instance of DefaultContextFactory by default, but this instance can be overridden using the function Amp\Parallel\Context\contextFactory().

Context factories are used by worker pools to create the context which executes tasks. Providing a custom ContextFactory to a worker pool allows custom bootstrapping or other behavior within pool workers.

An execution context can be created by a ContextFactory. The worker pool uses context factories to create workers.

A global worker pool is available and can be set using the function Amp\Parallel\Worker\workerPool(?WorkerPool $pool = null). Passing an instance of WorkerPool will set the global pool to the given instance. Invoking the function without an instance will return the current global instance.

IPC

A context is created with a single Channel which may be used to bidirectionally send data between the parent and child. Channels are a high-level data exchange, allowing serializable data to be sent over a channel. The Channel implementation handles serializing and unserializing data, message framing, and chunking over the underlying socket between the parent and child.

Note Channels should be used to send only data between the parent and child. Attempting to send resources such as database connections or file handles on a channel will not work. Such resources should be opened in each child process. One notable exception to this rule: server and client network sockets may be sent between parent and child using tools provided by amphp/cluster.

The example code below defines a class, AppMessage, containing a message type enum and the associated message data which is dependent upon the enum case. All messages sent over the channel between the parent and child use an instance of AppMessage to define message intent. Alternatively, the child could use a different class for replies, but that was not done here for the sake of brevity. Any messaging strategy may be employed which is best suited your application, the only requirement is that any structure sent over a channel must be serializable.

The example below sends a message to the child to process an image after receiving a path from STDIN, then waits for the reply from the child. When an empty path is provided, the parent sends null to the child to break the child out of the message loop and waits for the child to exit before exiting itself.

Creating an IPC socket

Sometimes it is necessary to create another socket for specialized IPC between a parent and child context. One such example is sending sockets between a parent and child process using ClientSocketReceivePipe and ClientSocketSendPipe, which are found in amphp/cluster. An instance of IpcHub in the parent and the Amp\Parallel\Ipc\connect() function in the child.

The example below creates a separate IPC socket between a parent and child, then uses amphp/cluster to create instances of ClientSocketReceivePipe and ClientSocketSendPipe in the parent and child, respectively.

Debugging

Step debugging may be used in child processes with PhpStorm and Xdebug by listening for debug connections in the IDE.

In PhpStorm settings, under PHP > Debug, ensure the box "Can accept external connections" is checked. The specific ports used are not important, yours may differ.

For child processes to connect to the IDE and stop at breakpoints set in the child processes, turn on listening for debug connections.

Listening off:

Listening on:

No PHP ini settings need to be set manually. Settings set by PhpStorm when invoking the parent PHP process will be forwarded to child processes.

Run the parent script in debug mode from PhpStorm with breakpoints set in code executed in the child process. Execution should stop at any breakpoints set in the child.

Debugger running:

When stopping at a breakpoint in a child process, execution of the parent process and any other child processes will continue. PhpStorm will open a new debugger tab for each child process connecting to the debugger, so you may need to limit the amount of child processes created when debugging or the number of connections may become overwhelming! If you set breakpoints in the parent and child process, you may need to switch between debug tabs to resume both the parent and child.

Versioning

amphp/parallel follows the semver semantic versioning specification like all other amphp packages.

Security

If you discover any security related issues, please use the private security issue reporter instead of using the public issue tracker.

License

The MIT License (MIT). Please see LICENSE for more information.