diff options
Diffstat (limited to 'buildscripts/phing/classes/phing/contrib/DocBlox/Parallel/README.md')
-rw-r--r-- | buildscripts/phing/classes/phing/contrib/DocBlox/Parallel/README.md | 106 |
1 files changed, 106 insertions, 0 deletions
diff --git a/buildscripts/phing/classes/phing/contrib/DocBlox/Parallel/README.md b/buildscripts/phing/classes/phing/contrib/DocBlox/Parallel/README.md new file mode 100644 index 00000000..272d7191 --- /dev/null +++ b/buildscripts/phing/classes/phing/contrib/DocBlox/Parallel/README.md @@ -0,0 +1,106 @@ +Parallel +======== + +This is a library for introducing Parallelization into your project. +See the `example.php` file for an example how to use this library. + +Theory of Operation +------------------- + +This library will enable the developer to execute a given amount of tasks +(workers) in parallel. This is achieved by adding workers onto a manager, +optionally defining how many processes to run simultaneously and then execute +the manager. + +Under Linux this library will try to detect the number of processors and allow +a maximum number of processes to run equal to the number of processors. If this +cannot be determined or the user is running Windows then a default of 2 is used. + +Requirements and graceful degradation +------------------------------------- + +Parallelization has several requirements. But to allow distribution, without +adding several requirements to your application, will this library execute the +given tasks in serie if the requirements are not met. And throw a E_USER_NOTICE +php error that explains to the user that dependencies are missing. + +The requirements for this library are: + +* A *NIX compatible operating system +* Scripts must not run from an apache module +* the PCNTL PHP extension (http://php.net/manual/en/book.pcntl.php) + +Workers +------- + +Workers are basically wrappers around callback functions or methods. As such you +can use anything in your existing project and parallelize it. + +Do note that each parallel process is a duplicate of the original. This means +that, for example, if you pass an object (or other reference) and change that, +that the changes that you have made do not carry over to the caller. + +The return value of the given callback is stored as result on the worker and +can be read using the `getResult()` method. + +Any exception that is thrown will result in an error, where the `getReturnCode()` +method will return the exception code (be warned: this may be 0!) and the +`getError()` method will return the exception message. + +Errors and exceptions +--------------------- + +if a task throws an exception it is caught and registered as an error. The +exception's code is used as error number, where the message is used as error +message. + +By using this, instead of dying, you can continue execution of the other parallel +processes and handle errors yourself after all processes have been executed. + +Examples +-------- + +### Fluent interface + + $mgr = new DocBlox_Parallel_Manager(); + $mgr + ->addWorker(new DocBlox_Parallel_Worker(function() { sleep(1); return 'a'; })) + ->addWorker(new DocBlox_Parallel_Worker(function() { sleep(1); return 'b'; })) + ->addWorker(new DocBlox_Parallel_Worker(function() { sleep(1); return 'c'; })) + ->addWorker(new DocBlox_Parallel_Worker(function() { sleep(1); return 'd'; })) + ->addWorker(new DocBlox_Parallel_Worker(function() { sleep(1); return 'e'; })) + ->execute(); + + /** @var DocBlox_Parallel_Worker $worker */ + foreach ($mgr as $worker) { + var_dump($worker->getResult()); + } + +### Array interface + + $mgr = new DocBlox_Parallel_Manager(); + $mgr[] = new DocBlox_Parallel_Worker(function() { sleep(1); return 'f'; }); + $mgr[] = new DocBlox_Parallel_Worker(function() { sleep(1); return 'g'; }); + $mgr[] = new DocBlox_Parallel_Worker(function() { sleep(1); return 'h'; }); + $mgr[] = new DocBlox_Parallel_Worker(function() { sleep(1); return 'i'; }); + $mgr[] = new DocBlox_Parallel_Worker(function() { sleep(1); return 'j'; }); + $mgr->execute(); + + /** @var DocBlox_Parallel_Worker $worker */ + foreach ($mgr as $worker) { + var_dump($worker->getResult()); + } + +TODO +---- + +* Improve docs +* More intelligent process slots; currently only the oldest in a 'set' of slots + is waited on but if this runs for a longer time then the other slots than + those will not be filled as long as the first slot is occupied. +* Last parts of IPC (Inter-Process Communication), to be able to return + information from Workers to the Manager. + + * STDOUT + * STDERR + |