Threading for PHP - Share Nothing, Do Everything :)

This project provides limited support for threading in PHP CLI.

This is a fork of the now-abandoned krakjoe/pthreads extension.

Managing expectations

While the idea of PHP threading may seem great, the barrier to using threads is much higher than other languages, due to severe limitations imposed by the design of the Zend Engine. Many things are not possible with threads in PHP, or are simply far too performance-intensive to be worthwhile.

You can learn more about pthreads at the following links:

Documentation

Documentation can be found in the .stub.php files stubs folder, and some examples can be found in the examples folder.

Legacy documentation for pthreads v2/v3 can be found here.

Fork focus

This fork is used in production on thousands of PocketMine-MP servers worldwide. Therefore, the focus is on performance and stability.

Changes compared to the original

PHP 8.1 and 8.2 support
Revamped API - significantly easier to work with and make sense of
No magic behaviour - no more object serialization, array -> Volatile magic behaviour removed
Clearer limits - no more hiding behind weird magic hacks to make things sort-of work
Many bug fixes which were never merged upstream
Performance improvements
Memory usage improvements
Integration with OPcache on PHP 7.4+ (pmmpthread leverages opcache SHM to reuse classes and functions, saving lots of memory)
OPcache JIT support on PHP 8.0.2+

OPcache compatibility

Despite popular belief, OPcache is still useful in a CLI environment - as long as it's a threaded one :) Every thread in pmmpthread is like a web server "request", so while OPcache doesn't offer as big an advantage to an application using pmmpthread as it does to a web server, it's far from useless.

If you're using PHP 7.4+, using OPcache with pmmpthread is strongly recommended, as you'll get various benefits from doing so:

Reduced memory usage when the same class is used on several threads
Better performance of starting new threads when threads inherit classes and functions

Preloading classes and functions is also supported on PHP 7.4, which will make classes available to all threads without an autoloader.

OPcache isn't enabled in the CLI by default, so you'll need to add

opcache.enable_cli=1

to your php.ini file.

Why not drop pmmpthread and move on to something newer and easier to work with, like krakjoe/parallel?

We found parallel too limited for the use cases we needed it for. If it had some thread-safe class base like Threaded (ThreadedBase or ThreadSafe in newer versions), it might be more usable.
It's possible to implement parallel's API using pthreads/pmmpthread, but not the other way round.
parallel requires significant migration efforts for code using pthreads/pmmpthread.

Some specific nitpicks which were deal-breakers for parallel usage in PocketMine-MP:

parallel has confusing and inconsistent behaviour surrounding object copying.
parallel has uncontrollable behaviour around its object copying routine (it's not possible to customise copies or prevent copies from occurring).

Updating pthreads to PHP 7.4 allowed PocketMine-MP users to immediately gain the benefits of PHP 7.4 without needing to suffer API breaks that would affect plugins. In addition, PHP 7.4 introduced various new internal features which are highly beneficial specifically to pthreads, such as immutable classes and op_arrays.

Requirements

PHP 7.4+
PHP CLI (only CLI is supported; pmmpthread is not intended for usage on a webserver)
ZTS Enabled ( Thread Safety )
Posix Threads Implementation (pthread-w32 / pthreads4w on Windows)

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

Unix-based Building from Source

Building pmmpthread 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 pmmpthread
phpize
./configure
make
make install (may need sudo)
Update your php.ini file to load the pmmpthread.so file using the extension directive

Windows-based Building from Source

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

Simple Windows Installation

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

Mac OSX Support

Yes !! Users of Mac will be glad to hear that pmmpthread 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();
?>

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 pmmpthread, 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.

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.

pmmp/ext-pmmpthread