ssigwart / process-pool
Process pool to send tasks to a background task.
Requires
- php: >=7.0.0
Requires (Dev)
- phpunit/phpunit: ^9
README
This package allows you to run a process pool. The pool will multiple background processes to handle messages to the pool. You can specific the minimum and maximum number of pool processes to run.
Creating a Pool
$minPoolSize = 1; $maxPoolSize = 10; $poolProcessCmd = 'php process.php'; $cwd = '/path/to/pool/process'; $pool = new ProcessPool($minPoolSize, $maxPoolSize, $poolProcessCmd, $cwd); $pool->setMaxNumSpareProcesses(3);
Implementing a Pool Process
The pool process should implement ssigwart\ProcessPool\ProcessPoolProcessMessageHandlerInterface
.
The handleRequest
function should handle incoming requests.
It can output to stdout
and stderr
, which can be read with getStdoutResponse
and getStderrResponse
.
Below is an example of what /path/to/pool/process/process.php
might look like.
<?php use ssigwart\ProcessPool\ProcessPoolProcess; use ssigwart\ProcessPool\ProcessPoolProcessMessageHandlerInterface; /** My example process */ class MyExampleProcess implements ProcessPoolProcessMessageHandlerInterface { /** * Handle exit request */ public function handleExit() { // You can do cleanup here, then call exit print 'Existing now.' . PHP_EOL; exit; } /** * Handle request * * @param string $data Data */ public function handleRequest(string $data) { // Handle $data here // Anything you output will be returned as STDOUT print 'You sent data ' . $data . PHP_EOL; // You can use error_log to output to STDERR error_log('This will be returned as STDERR.'); } } $proc = new ProcessPoolProcess(new MyExampleProcess()); $proc->handleMessages();
Sending a Message to the Pool
- Start a process
$req1 = $pool->startProcess(); $req1->sendRequest('Your message');
-
At this point, you should add
$req1
to an array of pending requests and send any other message you need to the queue. At some point in the future, you should check if and of those processes have data yet by callinghasStdoutData()
andhasStderrData()
. -
Get output and release process so if can be used for another request
$output = $req1->getStdoutResponse();
$errorOutput = $req1->getStderrResponse();
$pool->releaseProcess($req1);
Classes and Public API
ProcessPool
The process pool is used to maintain the pool state and start and stop processes.
Constructor (__construct
)
setMaxNumSpareProcesses
Sets the maximum number of spare processes to leave running in the pool after they complete a request, but are waiting for a new request.
getNumRunningProcesses
Returns the number of running processes. A running process is one that is actively handling a request at the moment.
getNumUnassignedProcesses
Returns the number of unassigned processes. An unassigned process is one that is waiting for a request to process.
startProcess
Starts a new process.
IMPORTANT! Remember to call releaseProcess
on the pool to free the resources of the process when you're done with it.
This may throw a ProcessPoolPoolExhaustedException
if the pool has reached the maximum number of allowed processes.
It returns a ProcessPoolRequest
that you can send your request to.
releaseProcess
This releases a process started with startProcess
and allows it to go back into the spare process pool to handle additional requests.
shutDown
This sends "exit" requests to all processes and closes them. This should only be called after handling all open processes and the pool should not be used after this. Often, you don't need to call this function as the pool registers a shutdown function.
ProcessPoolRequest
Represents a pool request that can process a single request.
sendRequest
hasFailed
Returns true if the process handling the request has failed.
waitForStdoutOrStderr
Waits for data on STDOUT or STDERR.
The returns true if there's data available. If so, hasStdoutData
and hasStderrData
should be called.
hasStdoutData
Returns true if the request has STDOUT data available.
Note that this may return true when EOF, but the data returned from getStdoutResponse
may be an empty string.
hasStderrData
Returns true if the request has STDERR data available.
Note that this may return true when EOF, but the data returned from getStderrResponse
may be an empty string.
getStdoutResponse
Returns STDOUT response from the process.
getStderrResponse
Returns STDERR response from the process.
Other Methods
There are additional public function that you should not call directly.
These include sendExitRequest
, freeRequest
, and close
.
ProcessPoolProcess
This is used by the background process to wait for and handle incoming messages from the pool.
Constructor (__construct
)
handleMessages
This function does the work of waiting for message and returning output to the parent pool process.