# parallel

&reftitle.intro;

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

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

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.

&reftitle.seealso;

- philosophy.parallel

&reference.parallel.setup; &reference.parallel.philosophy; &reference.parallel.functional; &reference.parallel.parallel.runtime; &reference.parallel.parallel.future; &reference.parallel.parallel.channel; &reference.parallel.parallel.events; &reference.parallel.parallel.events.input; &reference.parallel.parallel.events.event; &reference.parallel.parallel.events.event.type; &reference.parallel.parallel.sync;