Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/krakjoe/pthreads
Threading for PHP - Share Nothing, Do Everything :)
https://github.com/krakjoe/pthreads
Last synced: 2 months ago
JSON representation
Threading for PHP - Share Nothing, Do Everything :)
- Host: GitHub
- URL: https://github.com/krakjoe/pthreads
- Owner: krakjoe
- License: other
- Archived: true
- Created: 2012-08-28T17:57:40.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2019-11-09T18:39:09.000Z (about 5 years ago)
- Last Synced: 2024-07-31T19:16:02.684Z (5 months ago)
- Language: C
- Homepage:
- Size: 2.5 MB
- Stars: 3,473
- Watchers: 213
- Forks: 502
- Open Issues: 54
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-php-extensions - pthreads - 多线程 (异步)
README
# Threading for PHP - Share Nothing, Do Everything :)
[](https://travis-ci.org/krakjoe/pthreads)
[](https://ci.appveyor.com/project/krakjoe/pthreads/branch/master)
[](http://isitmaintained.com/project/krakjoe/pthreads "Average time to resolve an issue")
[](http://isitmaintained.com/project/krakjoe/pthreads "Percentage of issues still open")
[](https://gitter.im/krakjoe/pthreads?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
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](http://blog.krakjoe.ninja/2015/08/a-letter-from-future.html)
* [Addendum to A Letter from the Future](http://blog.krakjoe.ninja/2015/09/addendum-letter-from-future.html)
### 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
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](http://github.com/krakjoe/pthreads-polyfill) which can be found on [packagist](https://packagist.org/packages/krakjoe/pthreads-polyfill).
Having required the appropriate package in your composer.json, the following code is executable everywhere:
```php
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](http://blog.krakjoe.ninja/2015/09/what-polly-really-wants.html).
### 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.