Introduction

pthreads is an object-orientated API that provides all of the tools needed
for multi-threading in PHP. PHP applications can create, read, write,
execute and synchronize with Threads, Workers and Threaded objects.

Warning

The pthreads extension cannot be used in a web server environment.
Threading in PHP is therefore restricted to CLI-based applications only.

Warning

pthreads (v3) can only be used with PHP 7.2+: This is due to ZTS
mode being unsafe in 7.0 and 7.1.

The Threaded class forms the basis of the
functionality that allows pthreads to operate. It exposes synchronization
methods and some useful interfaces for the programmer.

The Thread class enables for threads to be created by
simply extending it and implementing a run method. Any
members can be written to and read by any context with a reference to the
thread. Any context can also execute any public and protected methods.
The body of the run method will be executed in a separate thread when the
Thread::start() method of the implementation is
called from the context that created it. Only the context that creates a
thread can start and join it.

The Worker class has a persistent state, and will be
available from the call to Thread::start() (an
inherited method) until the object goes out of scope, or is explicitly
shutdown (via Worker::shutdown()). Any context with a
reference to the worker object can stack tasks onto the Worker (via
Worker::stack()), where these tasks will be executed
by the worker in a separate thread. The run method of a
worker object will be executed before any objects on the worker's stack,
enabling for resources to be initialized that the objects to be executed may
need.

The Pool class is used to create a group of workers
to distribute Threaded objects amongst them. It is
the easiest and most efficient way of using multiple threads in PHP
applications.

Caution

The Pool class does not extend the
Threaded class, and so pool-based objects are
considered a normal PHP objects. As such, its instances of it should not be
shared amongst different contexts.

The Volatile class is new to pthreads v3. It is used
to denote mutable Threaded properties of
Threaded classes (since these are now immutable by
default). It is also used to store PHP arrays in
Threaded contexts.

Synchronization is an important ability when threading. All of the objects
that pthreads creates have built in synchronization in the (which will be
familiar to java programmers) form of
Threaded::wait() and
Threaded::notify(). Calling
Threaded::wait() on an object will cause the context
to wait for another context to call
Threaded::notify() on the same object. This mechanism
allows for powerful synchronization between Threaded
objects in PHP.

Caution

Any objects that are intended for use in the multi-threaded parts of your
application should extend Threaded.

Data Storage:
As a rule of thumb, any data type that can be serialized can be used as a member of a Threaded object, it can be read and written from any context with a reference to the Threaded Object.
Not every type of data is stored serially, basic types are stored in their true form.
Complex types, Arrays, and Objects that are not Threaded are stored serially; they can be read and written to the Threaded Object from any context with a reference.
With the exception of Threaded Objects any reference used to set a member of a Threaded Object is separated from the reference in the Threaded Object;
the same data can be read directly from the Threaded Object at any time by any context with a reference to the Threaded Object.

Static Members:
When a new context is created ( Thread or Worker ), they are generally copied, but resources and objects with internal state are nullified (for safety reasons). This allows them to function as a kind of thread local storage. For example, upon starting the context, a class whose static members include connection information for a database server, and the connection itself, will only have the simple connection information copied, not the connection. Allowing the new context to initiate a connection in the same way as the context that created it, storing the connection in the same place without affecting the original context.

Caution

When print_r, var_dump and other object debug functions are executed, they do not include recursion protection.

Note:

Resources:
The extensions and functionality that define resources in PHP are completely unprepared for this kind of environment; pthreads makes provisions for Resources to be shared among contexts, however, for most types of resource it should be considered unsafe. Extreme caution and care should be used when sharing resources among contexts.

Caution

In the environment which pthreads executes, some restrictions and limitations are necessary in order to provide a stable environment.