stephanschuler / fork-job-runner
Installs: 2 336
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Requires
- php: ^7.2
- ext-pcntl: *
- ext-posix: *
Requires (Dev)
- phpstan/phpstan: ^0.12
- phpunit/phpunit: ^6.0
This package is auto-updated.
Last update: 2024-10-21 15:06:48 UTC
README
Creating child processes is expensive, especially when this comes with bootstrapping huge parts of a framework.
This package constantly holds a single PHP process at a certain bootstrap level and forks this process whenever a job is to be executed.
All the demo code blow is to be implemented by the project, it is not provided by this package.
This package does not aim for parallel processing. This might work but other libraries or frameworks like e.g. ReactPHP are way better suited for this.
The primary objective is providing a technical basis for message queues in functional tests. There is specifically the Flowpack Jobqueue Common package shipping a Fake Queue where this package is meant to help providing a replacement.
Jobs
Every code that should be run in a separate process is called a Job
. Jobs are
created by the parent, serialized, passed to the worker child and unserialized
prior to execution. This needs to be considered, especially when dealing with
database connections, file pointers and other resources.
<?php declare(strict_types=1); namespace StephanSchuler\Demo; use StephanSchuler\ForkJobRunner\Utility\WriteBack; use StephanSchuler\ForkJobRunner\Job; class DemoJob implements Job { public function run(WriteBack $writeBack): void { // Do something } }
The Job
is a regular class definition. Put it in your project where it can be
found by the autoloader.
Dispatching
Passing a job from the parent process to isolated execution is called dispatching. There is no routing mechanism to hand jobs to different works nor is it this packages intention to execute jobs asynchronously or in parallel.
<?php declare(strict_types=1); namespace StephanSchuler\Demo; use StephanSchuler\ForkJobRunner\Dispatcher; $dispatcher = Dispatcher::create( \escapeshellcmd(\PHP_BINARY) . ' ' . \escapeshellarg(\__DIR__ . '/loop.php') ); $dispatcher->run( new DemoJob() );
Creating the dispatcher should be done only once because each dispatcher keeps its own worker process around.
Dispatching should be done wherever needed, e.g. within action methods in MVC controllers or in test methods of unit tests.
The Loop
The Loop
is the child process waiting for the incoming Job
. The Dispatcher
initializes the Loop
and passes Job
s along.
This is meant to be a CLI entry point. It's the "loop.php" file mentioned in the
example code of the Dispatcher
.
<?php declare(strict_types=1); use StephanSchuler\ForkJobRunner\Dispatcher; use StephanSchuler\ForkJobRunner\Loop; require(__DIR__ . '/vendor/autoload.php'); // Bootstrap framework here Loop::create() ->run();
The Loop::run()
method does never return unless the dispatchers command stream
is open.
Responding
Jobs can respond to the dispatching process. Every serializable data can be
passed from Job
to Dispatcher
.
<?php declare(strict_types=1); use StephanSchuler\ForkJobRunner\Utility\WriteBack; use StephanSchuler\ForkJobRunner\Dispatcher; use StephanSchuler\ForkJobRunner\Job; use StephanSchuler\ForkJobRunner\Response; class DemoJob implements Job { public function run(WriteBack $writer) : void { $writer->send( new Response\DefaultResponse('this goes to stdout') ); $writer->send( new Response\ThrowableResponse( new RuntimeException('This is an exception') ) ); throw new RuntimeException('This is another exception'); } } assert($dispatcher instanceof Dispatcher); $job = new DemoJob(); $responses = $dispatcher->run($job); foreach ($responses as $response) { switch (true) { case ($response instanceof Response\NoOpResponse): // No Op responses act as keep alive signal. // There is at least two per job, one at the beginning and one // at the end. break; case ($response instanceof Response\DefaultResponse): // Default responses contain text. // They are not used internally. \fputs(\STDOUT, $response->get()); break; case ($response instanceof Response\ThrowableResponse): // This catches both, // the explicite call of $writer->send() // as well as the thrown exception. \fputs(\STDERR, print_r($response->get(), true)); break; case ($response instanceof Response\Response): // Feel free to implement custom responses. break; } }