symplely/thread_queue

An simply `uv_queue_work` wrapper API to manage a pool of threads, for parallel PHP execution

dev-main 2023-03-19 15:21 UTC

Requires

• php: >7.1

Requires (Dev)

• phpunit/phpunit: ^8

Suggests

• ext-uv: >0.2.4

MIT

• Lawrence Stubbs

• async
• parallel
• asynchronous
• Thread
• libuv
• uv_queue_work

README

An simply uv_queue_work wrapper API to manage a pool of threads, for parallel PHP execution.

Table of Contents

• Installation
• Usage
• Event hooks
• Contributing
• License

This package uses features of libuv, the PHP extension ext-uv of the Node.js library. It's uv_queue_work function is used to create Threads.

Installation

composer require symplely/thread_queue

This package will require libuv features, do one of the following to install.

For Debian like distributions, Ubuntu...

apt-get install libuv1-dev php-pear -y

For RedHat like distributions, CentOS...

yum install libuv-devel php-pear -y

Now have Pecl auto compile, install, and setup.

pecl channel-update pecl.php.net
pecl install uv-beta

For Windows, stable PHP versions are available from PECL.

Directly download latest from https://windows.php.net/downloads/pecl/releases/uv/

Extract libuv.dll to same directory as PHP binary executable, and extract php_uv.dll to ext\ directory.

Enable extension php_uv.dll in php.ini

cd C:\Php
Invoke-WebRequest "https://windows.php.net/downloads/pecl/releases/uv/0.2.4/php_uv-0.2.4-7.2-ts-vc15-x64.zip" -OutFile "php_uv-0.2.4.zip"
#Invoke-WebRequest "https://windows.php.net/downloads/pecl/releases/uv/0.2.4/php_uv-0.2.4-7.4-ts-vc15-x64.zip" -OutFile "php_uv-0.2.4.zip"
7z x -y php_uv-0.2.4.zip libuv.dll php_uv.dll
copy php_uv.dll ext\php_uv.dll
del php_uv.dll
del php_uv-0.2.4.zip
echo extension=uv >> php.ini

Usage

include 'vendor/autoload.php';

use Async\Threads\Thread;

$thread = new Thread();
$counter = 0;
$t1 = $thread->create_ex(function () {
  print "Running Thread: 1\n";
  return 2;
})->then(function (int $output) use (&$counter) {
  $counter += $output;
})->catch(function (\Throwable $e) {
  print $e->getMessage() . PHP_EOL;
});

$t1->join();
// Or
$t1->cancel();

print_r($t1->result());
// Or
print_r($t1->exception());

Event hooks

When creating Threads processes, you'll get an instance of TWorker returned. You can add the following event callback hooks on a Thread instance.

$thread = new Thread($function, ...$args)

$worker = $thread->create($thread_id /* string or int */, function () {
    }, ...$arguments)
    ->then(function ($result) {
        // On success, `$result` is returned by the thread.
    })
    ->catch(function ($exception) {
        // When an exception is thrown from within a thread, it's caught and passed here.
    });

$worker = $thread->create_ex(function () {
    }, ...$arguments)
    ->then(function ($result) {
        // On success, `$result` is returned by the thread.
    })
    ->catch(function ($exception) {
        // When an exception is thrown from within a thread, it's caught and passed here.
    });

Contributing

Contributions are encouraged and welcome; I am always happy to get feedback or pull requests on Github :) Create Github Issues for bugs and new features and comment on the ones you are interested in.

License

The MIT License (MIT). Please see License File for more information.