# pthreads

# 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

This extension is considered unmaintained and dead.

Tip

Consider using parallel instead.

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.

- Installing/Configuring
  - Requirements
  - Installation
- Predefined Constants
- Threaded — The Threaded class
  - Threaded::chunk — Manipulation
  - Threaded::count — Manipulation
  - Threaded::extend — Runtime Manipulation
  - Threaded::isRunning — State Detection
  - Threaded::isTerminated — State Detection
  - Threaded::merge — Manipulation
  - Threaded::notify — Synchronization
  - Threaded::notifyOne — Synchronization
  - Threaded::pop — Manipulation
  - Threaded::run — Execution
  - Threaded::shift — Manipulation
  - Threaded::synchronized — Synchronization
  - Threaded::wait — Synchronization
- Thread — The Thread class
  - Thread::getCreatorId — Identification
  - Thread::getCurrentThread — Identification
  - Thread::getCurrentThreadId — Identification
  - Thread::getThreadId — Identification
  - Thread::isJoined — State Detection
  - Thread::isStarted — State Detection
  - Thread::join — Synchronization
  - Thread::start — Execution
- Worker — The Worker class
  - Worker::collect — Collect references to completed tasks
  - Worker::getStacked — Gets the remaining stack size
  - Worker::isShutdown — State Detection
  - Worker::shutdown — Shutdown the worker
  - Worker::stack — Stacking work
  - Worker::unstack — Unstacking work
- Collectable — The Collectable interface
  - Collectable::isGarbage — Determine whether an object has been marked as garbage
- Pool — The Pool class
  - Pool::collect — Collect references to completed tasks
  - Pool::__construct — Creates a new Pool of Workers
  - Pool::resize — Resize the Pool
  - Pool::shutdown — Shutdown all workers
  - Pool::submit — Submits an object for execution
  - Pool::submitTo — Submits a task to a specific worker for execution
- Volatile — The Volatile class

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open