Introduction

parallel is a parallel concurrency extension for PHP ≥ 7.2.0. As of parallel 1.2.0, PHP ≥ 8.0.0 is required.

A brief description of the concepts core to parallel follows, more detailed information may be found within this section of the manual.

Runtime

A parallel\Runtime represents a PHP interpreter thread. A parallel\Runtime is configured with an optional bootstrap file passed to parallel\Runtime::__construct, this is typically an autoloader, or some other preloading routine: The bootstrap file will be included before any task is executed.

After construction the parallel\Runtime remains available until it is closed, killed, or destroyed by the normal scoping rules of PHP objects. parallel\Runtime::run allows the programmer to schedule tasks for execution in parallel. A parallel\Runtime has a FIFO schedule, tasks will be executed in the order that they are scheduled.

Functional API

parallel implements a functional, higher level API on top of parallel\Runtime that provides a single function entry point to executing parallel code with automatic scheduling: parallel\run.

Task

A task is simply a Closure intended for parallel execution. The Closure may contain almost any instruction, including nested closures. However, there are some instructions that are prohibited in tasks:

yield
use by-reference
declare class
declare named function

Note:
Nested closures may yield or use by-reference, but must not contain class or named function declarations.

Note:
No instructions are prohibited in the files which the task may include.

Future

The parallel\Future is used to access the return value from the task, and exposes an API for cancellation of the task.

Channel

A task may be scheduled with arguments, use lexical scope variables (by-value), and return a value (via a parallel\Future), but these only allow uni-directional communication: They allow the programmer to send data into and retrieve data from a task, but do not allow bi-directional communication between tasks. The parallel\Channel API allows bi-directional communication between tasks, a parallel\Channel is a socket-like link between tasks that the programmer can use to send and receive data.

Events

The parallel\Events API implements a native feel (Traversable) event loop, and parallel\Events::poll method. It allows the programmer to work with sets of channels and or futures. The programmer simply adds channels and futures to the event loop, optionally setting the input for writes with parallel\Events::setInput, and enters into a foreach: parallel will read from and write to objects as they become available yielding parallel\Events\Event objects describing the operations that have occurred.