General fixes, docblock updates and comments, BC

- added `displayOn()` and `display()` to show child process output when using `wait()/run()`
- updated required, name changes

Processor/Container.php

@@ -3,7 +3,6 @@
 declare(strict_types=1);
 
 use Async\Processor\Processor;
-use Async\Processor\ProcessorError;
 use Async\Processor\SerializableException;
 
 try {

Processor/Launcher.php

@@ -90,6 +90,14 @@ public function yielding()
         return yield from $this->run(true);
     }
 
+    public function display()
+    {
+        if ($this->showOutput) {
+            \printf('%s', $this->getRealOutput());
+            $this->realOutput = null;
+        }
+    }
+
     public function wait($waitTimer = 1000, bool $useYield = false)
     {
         while ($this->isRunning()) {
@@ -101,10 +109,7 @@ public function wait($waitTimer = 1000, bool $useYield = false)
                 return $this->triggerTimeout();
             }
 
-            if ($this->showOutput) {
-                \printf('%s', $this->getRealOutput());
-                $this->realOutput = null;
-            }
+            $this->display();
 
             if ($useYield)
                 $this->yieldLiveUpdate($this->getRealOutput());
@@ -153,7 +158,7 @@ public function isRunning(): bool
         return $this->process->isRunning();
     }
 
-    public function showOutput(): self
+    public function displayOn(): self
     {
         $this->showOutput = true;
 

Processor/LauncherInterface.php

@@ -4,6 +4,8 @@
 
 namespace Async\Processor;
 
+use Async\Processor\Process;
+
 interface LauncherInterface
 {
     /**
@@ -169,9 +171,22 @@ public function isTerminated(): bool;
     public function isSuccessful(): bool;
 
     /**
-     * Set process to display output of parent process.
+     * Set process to display output of child process.
      *
      * @return LauncherInterface
      */
-    public function showOutput();
+    public function displayOn();
+
+    /**
+     * Display child process output, if set.
+     */
+    public function display();
+
+
+    /**
+     * A PHP process
+     *
+     * @return Process
+     */
+    public function getProcess(): Process;
 }

Processor/functions.php

@@ -20,8 +20,11 @@ function spawn($shellCallable, int $timeout = 300, $processChannel = null): Laun
     return Processor::create($shellCallable, $timeout, $processChannel);
   }
 
-  function spawn_run(LauncherInterface $process)
+  /**
+   * Start the process and wait to terminate, and return results in index array.
+   */
+  function spawn_run(LauncherInterface $process, bool $displayOutput = false)
   {
-    return $process->run();
+    return $displayOutput ? $process->displayOn()->run() : $process->run();
   }
 }

README.md

@@ -38,11 +38,16 @@ $process = Processor::create(function () use ($thing) {
 \spawn_run($process);
 // Or
 $process->run();
+
+// Second option can be used to set to display child output, default is false
+\spawn_run($process, true);
+// Or
+$process->displayOn()->run();
 ```
 
 ## Event hooks
 
-When creating asynchronous processes, you'll get an instance of `ProcessInterface` returned.
+When creating asynchronous processes, you'll get an instance of `LauncherInterface` returned.
 You can add the following event hooks on a process.
 
 ```php
@@ -85,6 +90,12 @@ There also `->done`, and `->progress` part of `->then()` extended callback metho
     }
 );
 
+// To turn on to display child output.
+->displayOn();
+
+// To display child output, only by third party means once turned on.
+->display();
+
 // Processes can be retried.
 ->restart();
 ->run();

phpunit.xml.dist

@@ -3,30 +3,29 @@
          backupGlobals="false"
          backupStaticAttributes="false"
          colors="true"
-         verbose="true" 
+         verbose="true"
          convertErrorsToExceptions="true"
          convertNoticesToExceptions="true"
          convertWarningsToExceptions="true"
          processIsolation="false"
          stopOnFailure="false">
-	
+
     <testsuites>
         <testsuite name="Processor Test Suite">
             <directory suffix=".php">tests/</directory>
         </testsuite>
     </testsuites>
-	
+
     <filter>
         <whitelist>
             <directory suffix=".php">Processor/</directory>
             <exclude>
                 <file>./Processor/Container.php</file>
             </exclude>
-        </whitelist>		
+        </whitelist>
     </filter>
-	
+
 	<logging>
-        <log type="tap" target="build/report.tap"/>
         <log type="junit" target="build/report.junit.xml"/>
         <log type="coverage-html" target="build/coverage"/>
         <log type="coverage-text" target="build/coverage.txt"/>

tests/ErrorHandlingTest.php

@@ -2,8 +2,6 @@
 
 namespace Async\Tests;
 
-use Error;
-use ParseError;
 use Async\Processor\Processor;
 use Async\Processor\ProcessorError;
 use PHPUnit\Framework\TestCase;

tests/ProcessorTest.php

@@ -2,7 +2,7 @@
 
 namespace Async\Tests;
 
-use InvalidArgumentException;
+use Async\Processor\Process;
 use Async\Processor\Processor;
 use Async\Processor\ProcessorError;
 use PHPUnit\Framework\TestCase;
@@ -86,6 +86,9 @@ public function testStart()
         $process = Processor::create(function () {
             usleep(1000);
         });
+
+        $this->assertTrue($process->getProcess() instanceof Process);
+        $this->assertIsNumeric($process->getId());
         $this->assertFalse($process->isRunning());
         $this->assertFalse($process->isTimedOut());
         $this->assertFalse($process->isTerminated());
@@ -105,7 +108,7 @@ public function testLiveOutput()
             usleep(1000);
         });
         $this->expectOutputString('hello child');
-        $process->showOutput()->run();
+        $process->displayOn()->run();
     }
 
     public function testGetOutputShell()