This project provides limited support for threading in PHP CLI.
This is a fork of the now-abandoned krakjoe/pthreads extension.
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 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.
This fork is used in production on thousands of PocketMine-MP servers worldwide. Therefore, the focus is on performance and stability.
array
-> Volatile
magic behaviour removedDespite 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:
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.
Threaded
(ThreadedBase
or ThreadSafe
in newer versions), it might be more usable.Some specific nitpicks which were deal-breakers for parallel usage in PocketMine-MP:
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.
Testing has been carried out on x86, x64 and ARM, in general you just need a compiler and pthread.h
Building pmmpthread from source is quite simple on Unix-based OSs. The instructions are as follows:
cd pmmpthread
phpize
./configure
make
make install
(may need sudo)pmmpthread.so
file using the extension
directiveYes !! Windows support is offered thanks to the pthread-w32 library.
pthreadVC2.dll
or pthreadVC3.dll
(included with the Windows releases) to the same directory as php.exe
eg. C:\xampp\php
php_pmmpthread.dll
to PHP extension folder eg. C:\xampp\php\ext
Yes !! Users of Mac will be glad to hear that pmmpthread is now tested on OSX as part of the development process.
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();
?>
Please submit issues, and send your feedback and suggestions as often as you have them.
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.
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.