README.md

Threading for PHP - Share Nothing, Do Everything :)

This project provides multi-threading that is compatible with PHP based on Posix Threads.

Highlights

• An easy to use, quick to learn OO Threading API for PHP 7.2+
• Execute any and all predefined and user declared methods and functions, including closures.
• Ready made synchronization included
• A world of possibilities ...

Technical Features

• High Level Threading
• Synchronization
• Worker Threads
• Thread Pools
• Complete Support for OO - ie. traits, interfaces, inheritance etc
• Full read/write/execute support for Threaded objects

Requirements

• PHP 7.2+
• ZTS Enabled ( Thread Safety )
• Posix Threads Implementation

Testing has been carried out on x86, x64 and ARM, in general you just need a compiler and pthread.h

PHP7

For PHP7, pthreads has been almost completely rewritten to be more efficient, easier to use and more robust. I will give a brief changelog here:

The API for v3 has changed, the following things have been removed:

• Mutex, Cond, and Stackable
• Threaded::lock and Threaded::unlock
• Threaded::isWaiting
• Threaded::from
• Thread::kill (there be dragons)
• Thread::detach
• Worker::isWorking
• Threaded::getTerminationInfo (this was unsafe, a better, safe impl can be done in userland)
• Special behaviour of protected and private methods on Threaded objects

The following things have significant changes:

• The method by which Threaded objects are stored as member properties of other Threaded objects.
• The structure used by a Worker for stack (Collectable objects to execute inserted by Worker::stack).
• The Pool::collect mechanism was moved from Pool to Worker for a more robust Worker and simpler Pool inheritance.
• The method by which iteration occurs on Threaded objects, such that it uses memory more efficiently.
• Threaded::synchronized provides true synchronization (state and properties lock).
• Worker objects no longer require that you retain a reference to Collectable objects on the stack.
• Unified monitor (cond/mutex/state) for Threaded objects
• Threaded members of Threaded objects are immutable
• Volatile objects, exempt from immutability
• array coerced to Volatile when set as member of Threaded
• Collectable converted to interface, to make extends Volatile implements Collectable possible.

Some blog posts explaining these changes:

• A Letter from the Future
• Addendum to A Letter from the Future

Supported PHP Versions

pthreads v3 requires PHP7 or above. PHP5 needs to use pthreads v2 which can be found in the PHP5 branch.

Note that only PHP 7.2+ is now supported (requiring the current master branch of pthreads). This is due to safety issues with ZTS mode on PHP 7.0 and 7.1.

Unix-based Building from Source

Building pthreads from source is quite simple on Unix-based OSs. The instructions are as follows:

• Clone this repository and checkout the release to use (or master for the latest updates)
• cd pthreads
• phpize
• ./configure
• make
• make install (may need sudo)
• Update your php.ini file to load the pthreads.so file using the extension directive

Windows Support

Yes !! Windows support is offered thanks to the pthread-w32 library.

Releases for Windows can be found: http://windows.php.net/downloads/pecl/releases/pthreads/

Simple Windows Installation

• Add pthreadVC2.dll (included with the Windows releases) to the same directory as php.exe eg. C:\xampp\php
• Add php_pthreads.dll to PHP extension folder eg. C:\xampp\php\ext

Mac OSX Support

Yes !! Users of Mac will be glad to hear that pthreads is now tested on OSX as part of the development process.

Hello World

As is customary in our line of work:

<?php
$thread = new class extends Thread {
	public function run() {
		echo "Hello World\n";
	}
};

$thread->start() && $thread->join();
?>

Are you serious ?

Absolutely, this is not a hack, we don't use forking or any other such nonsense, what you create are honest to goodness posix threads that are completely compatible with PHP and safe ... this is true multi-threading :)

SAPI Support

pthreads v3 is restricted to operating in CLI only: I have spent many years trying to explain that threads in a web server just don't make sense, after 1,111 commits to pthreads I have realised that, my advice is going unheeded.

So I'm promoting the advice to hard and fast fact: you can't use pthreads safely and sensibly anywhere but CLI.

Thanks for listening ;)

Documentation

Documentation can be found in the PHP manual: http://docs.php.net/manual/en/book.pthreads.php, and some examples can be found in the "examples" folder in the master repository.

Further insights and occasional announcements can be read at the http://pthreads.org site where pthreads is developed and tested in the real world.

Here are some links to articles I have prepared for users: everybody should read them before they do anything else:

• https://gist.github.com/krakjoe/6437782
• https://gist.github.com/krakjoe/9384409

If you have had the time to put any cool demo's together and would like them showcased on pthreads.org please get in touch.

Polyfill

It's possible to write code that optionally takes advantage of parallelism where the environment has pthreads loaded.

This is made possible by pthreads-polyfill which can be found on packagist.

Having required the appropriate package in your composer.json, the following code is executable everywhere:

<?php
require_once("vendor/autoload.php");

if (extension_loaded("pthreads")) {
	    echo "Using pthreads\n";
} else  echo "Using polyfill\n";

$pool = new Pool(4);

$pool->submit(new class extends Threaded {
        public function run() {
                echo "Hello World\n";
        }
});

while ($pool->collect()) continue;

$pool->shutdown();
?>

Some guidance on getting started, and detail regarding how the polyfill came to exist can be found here.

Feedback

Please submit issues, and send your feedback and suggestions as often as you have them.

Reporting Bugs

If you believe you have found a bug in pthreads, please open an issue: Include in your report minimal, executable, reproducing code.

Minimal: reduce your problem to the smallest amount of code possible; This helps with hunting the bug, but also it helps with integration and regression testing once the bug is fixed.

Executable: include all the information required to execute the example code, code snippets are not helpful.

Reproducing: some bugs don't show themselves on every execution, that's fine, mention that in the report and give an idea of how often you encounter the bug.

It is impossible to help without reproducing code, bugs that are opened without reproducing code will be closed.

Please include version and operating system information in your report.

Please do not post requests to help with code on github; I spend a lot of time on Stackoverflow, a much better place for asking questions.

Have patience; I am one human being.

Developers

There is no defined API for you to create your own threads in your extensions, this project aims to provide Userland threading, it does not aim to provide a threading API for extension developers. I suggest you allow users to decide what they thread and keep your own extension focused on your functionality.