update readme and stubs, tests, added signal example, and rename other

- update `uv_spawn` callback to just close all handles
- renamed function, allow to return results
- update readme about integration
- updated/added channnel class method to send kill to subprocess
- keep `libuv` doc/stubs in sync with [WIP] PR amphp/ext-uv#77

Author: TheTechsTech

README.md

@@ -106,12 +106,10 @@ $process = spawn(function (ChanneledInterface $channel) {
     echo $channel->read(); // same as echo fgets(STDIN);
     echo $channel->read();
 
-    // This is needed otherwise last output will be mixed in with the encoded return data.
+    // The `return_in` is needed otherwise last output will be mixed in with the encoded return data.
     // Or some other processing could be done instead to make this unnecessary.
-    returning(); // same as echo '___uv_spawn___'; usleep(50);
-
-    // all returned `data/results` are encoded, then decode by the parent.
-    return 'return whatever';
+    // All returned `data/results` are encoded, then decode by the parent.
+    return \return_in(50, 'return whatever'); // same as echo '___uv_spawn___'; usleep(50); return 'return whatever';
     }, 0, $ipc)
         ->progress(function ($type, $data) use ($ipc) {
             if ('ping' === $data) {
@@ -151,7 +149,7 @@ $process = Spawn::create(function () {
 
         /////////////////////////////////////////////////////////////
         // This following statement is needed or some other processing performed before returning data.
-        returning($delay); // will print '___uv_spawn___' and sleep for 50 microseconds;
+        \return_in($delay, $with); // will print '___uv_spawn___' and sleep for 50 microseconds with data;
         /////////////////////////////////////////////////////////////
 
         return `result`; // `result` will be encoded, then decoded by parent.
@@ -203,6 +201,8 @@ There's also `->done`, part of `->then()` extended callback method.
 ->run();
 ```
 
+## How to integrate into another project
+
 ```php
 /**
  * Setup for third party integration.
@@ -216,9 +216,64 @@ There's also `->done`, part of `->then()` extended callback method.
  * @param bool $useUv - Turn **on/off** `uv_spawn` for child subprocess operations, will use **libuv** features,
  * if not **true** will use `proc_open` of **symfony/process**.
  */
-spawn_setup($loop, $isYield, $bypass, $useUv)
+\spawn_setup($loop, $isYield, $bypass, $useUv)
 // Or
 Spawn::setup($loop = null, $isYield = true, $bypass = true, $useUv = true);
+
+// For checking and acting on each subprocess status use:
+
+/**
+ * Check if the process has timeout (max. runtime).
+ */
+ ->isTimedOut();
+
+/**
+ * Call the timeout callbacks.
+ */
+->triggerTimeout();
+
+/**
+ * Checks if the process received a signal.
+ */
+->isSignaled();
+
+/**
+ * Call the signal callbacks.
+ */
+->triggerSignal($signal);
+
+/**
+ * Checks if the process is currently running.
+ */
+->isRunning();
+
+/**
+ * Call the progress callbacks on the child subprocess output in real time.
+ */
+->triggerProgress($type, $buffer);
+
+/**
+ * Checks if the process ended successfully.
+ */
+->isSuccessful();
+
+/**
+ * Call the success callbacks.
+ * @return mixed
+ */
+->triggerSuccess();
+
+/**
+ * Checks if the process is terminated.
+ */
+->isTerminated();
+
+/**
+ * Call the error callbacks.
+ * @throws \Exception if error callback array is empty
+ */
+->triggerError();
+
 ```
 
 ## Error handling

Spawn/Channeled.php

@@ -89,7 +89,11 @@ public function send($message): ChanneledInterface
             throw new \RuntimeException(\sprintf('%s is closed', static::class));
         }
 
-        if ($this->channel !== null && $this->channel->getProcess() instanceof \UVProcess) {
+        if (
+            \is_object($this->channel)
+            && \method_exists($this->channel, 'getProcess')
+            && $this->channel->getProcess() instanceof \UVProcess
+        ) {
             \uv_write($this->channel->getPipeInput(), self::validateInput(__METHOD__, $message), function () {
             });
         } else {
@@ -99,9 +103,21 @@ public function send($message): ChanneledInterface
         return $this;
     }
 
+    /**
+     * @codeCoverageIgnore
+     */
+    public function kill(): void
+    {
+        if (\is_object($this->channel) && \method_exists($this->channel, 'stop')) {
+            $this->channel->stop();
+        }
+    }
+
     public function receive()
     {
-        return $this->channel->getLast();
+        if (\is_object($this->channel) && \method_exists($this->channel, 'getLast')) {
+            return $this->channel->getLast();
+        }
     }
 
     /**

Spawn/ChanneledInterface.php

@@ -15,7 +15,7 @@ interface ChanneledInterface extends \IteratorAggregate
     /**
      * Setup the `parent` IPC handle.
      *
-     * @param Object|Launcher $handle Use by `send()` and `receive()`
+     * @param Object|Launcher $handle Use by `send()`, `receive()`, and `kill()`
      *
      * @return ChanneledInterface
      */
@@ -57,6 +57,13 @@ public function isClosed(): bool;
      */
     public function send($message): ChanneledInterface;
 
+    /**
+     * Stop/kill the channel **child/subprocess** with `SIGKILL` signal.
+     *
+     * @return void
+     */
+    public function kill(): void;
+
     /**
      * Receive the last message from the IPC channel.
      */

Spawn/Core.php

@@ -288,6 +288,8 @@ function is_base64($input): ?bool
      *
      * @return void
      *
+     * @deprecated 1.1.3
+     *
      * @codeCoverageIgnore
      */
     function returning(int $microsecond = 50)
@@ -297,6 +299,41 @@ function returning(int $microsecond = 50)
         \usleep($microsecond);
     }
 
+    /**
+     * For use when/before calling the actual `return` keyword, will write `___uv_spawn___` to standard
+     * output and flush, then sleep for `microsecond`.
+     *
+     * The `___uv_spawn___` will be extracted from the encoded `return` data/result before being
+     * processed by other internal routines/methods.
+     *
+     * - For use with subprocess `ipc` interaction.
+     *
+     * - This function is intended to overcome an issue when **`return`ing** the `encode` data/results
+     * from an child subprocess operation.
+     *
+     * - The problem is the fact the last output is being mixed in with the `return` encode
+     * data/results.
+     *
+     * - The parent is given no time to read data stream before the `return`, there was no
+     *  delay or processing preformed between child last output and the `return` statement.
+     *
+     * @param int $microsecond - `50` when using `uv_spawn`, otherwise `1500` or so higher with `proc_open`.
+     *
+     * @param mixed $withData to return to parent process.
+     *
+     * @return void|mixed
+     */
+    function return_in(int $microsecond = 50, $withData = null)
+    {
+        \fwrite(\STDOUT, '___uv_spawn___');
+        \fflush(\STDOUT);
+        \usleep($microsecond);
+        \fflush(\STDOUT);
+
+        if (!\is_null($withData))
+            return $withData;
+    }
+
     /**
      * Setup for third party integration.
      *

Spawn/Launcher.php

@@ -160,8 +160,7 @@ public static function add(
 
                 foreach ([$in, $out, $err, $process] as $handle) {
                     if ($handle instanceof \UV) {
-                        \uv_close($handle, function () {
-                        });
+                        \uv_close($handle);
                     }
                 }
 

Spawn/UVFunctions.php

@@ -665,7 +665,8 @@ function uv_queue_work(UVLoop $loop, callable $callback, callable $after_callbac
 }
 
 /**
- * Initialize the handle.
+ * Initialize the `UVIdle` handle watcher.
+ * Idle watchers get invoked every loop iteration.
  *
  * @param UVLoop $loop uv_loop handle.
  *
@@ -676,7 +677,21 @@ function uv_idle_init(UVLoop $loop = null)
 }
 
 /**
- * Start the handle with the given callback.
+ * Start the Idle handle with the given callback.
+ *
+ * The callbacks of idle handles are invoked once per event loop.
+ *
+ * The idle callback can be used to perform some very low priority activity.
+ * For example, you could dispatch a summary of the daily application performance to the
+ * developers for analysis during periods of idleness, or use the application’s CPU time
+ * to perform SETI calculations :)
+ *
+ * An idle watcher is also useful in a GUI application.
+ *
+ * Say you are using an event loop for a file download. If the TCP socket is still being established
+ * and no other events are present your event loop will pause (block), which means your progress bar
+ * will freeze and the user will face an unresponsive application. In such a case queue up and idle
+ * watcher to keep the UI operational.
  *
  * @param UVIdle $idle uv_idle handle.
  * @param callable $callback expects (UVIdle $handle)
@@ -686,7 +701,7 @@ function uv_idle_start(UVIdle $idle, callable $callback)
 }
 
 /**
- * Stop the handle, the callback will no longer be called.
+ * Stop the Idle handle, the callback will no longer be called.
  *
  * @param UVIdle $idle uv_idle handle.
  */
@@ -695,7 +710,12 @@ function uv_idle_stop(UVIdle $idle)
 }
 
 /**
- * Initialize the handle.
+ * Initialize the `UVPrepare` handle watcher.
+ * Prepare watchers get invoked before polling for I/O events.
+ *
+ * Their main purpose is to integrate other event mechanisms into `libuv` and their
+ * use is somewhat advanced. They could be used, for example, to track variable changes,
+ * implement your own watchers.
  *
  * @param UVLoop $loop uv loop handle.
  *
@@ -706,7 +726,7 @@ function uv_prepare_init(UVLoop $loop = null)
 }
 
 /**
- * Start the handle with the given callback.
+ * Start the Prepare handle with the given callback.
  *
  * @param UVPrepare $handle UV handle (prepare)
  * @param callable $callback expects (UVPrepare $prepare, int $status).
@@ -716,7 +736,7 @@ function uv_prepare_start(UVPrepare $handle, callable $callback)
 }
 
 /**
- * Stop the handle, the callback will no longer be called.
+ * Stop the Prepare handle, the callback will no longer be called.
  *
  * @param UVPrepare $handle UV handle (prepare).
  */
@@ -725,7 +745,12 @@ function uv_prepare_stop(UVPrepare $handle)
 }
 
 /**
- * Initialize the handle.
+ * Initialize the `UVCheck` handle watcher.
+ * Check watchers get invoked after polling for I/O events.
+ *
+ * Their main purpose is to integrate other event mechanisms into `libuv` and their
+ * use is somewhat advanced. They could be used, for example, to track variable changes,
+ * implement your own watchers.
  *
  * @param UVLoop $loop uv loop handle
  *
@@ -736,21 +761,7 @@ function uv_check_init(UVLoop $loop = null)
 }
 
 /**
- * Start the handle with the given callback.
- *
- * The callbacks of idle handles are invoked once per event loop.
- *
- * The idle callback can be used to perform some very low priority activity.
- * For example, you could dispatch a summary of the daily application performance to the
- * developers for analysis during periods of idleness, or use the application’s CPU time
- * to perform SETI calculations :)
- *
- * An idle watcher is also useful in a GUI application.
- *
- * Say you are using an event loop for a file download. If the TCP socket is still being established
- * and no other events are present your event loop will pause (block), which means your progress bar
- * will freeze and the user will face an unresponsive application. In such a case queue up and idle
- * watcher to keep the UI operational.
+ * Start the Check handle with the given callback.
  *
  * @param UVCheck $handle UV handle (check).
  * @param callable $callback expects (UVCheck $check, int $status).
@@ -760,7 +771,7 @@ function uv_check_start(UVCheck $handle, callable $callback)
 }
 
 /**
- * Stop the handle, the callback will no longer be called.
+ * Stop the Check handle, the callback will no longer be called.
  *
  * @param UVCheck $handle UV handle (check).
  */

examples/spawn.php examples/progress.phpexamples/spawn.php renamed to examples/progress.php

@@ -14,8 +14,7 @@ function (ChanneledInterface $channel) {
         $channel->write('ping');
         echo $channel->read();
         echo $channel->read();
-        returning();
-        return 'The game!';
+        return \return_in(50, 'The game!');
     }
 )->progress(function ($type, $data) use ($ipc) {
     if ('ping' === $data) {

examples/signal.php

@@ -0,0 +1,35 @@
+<?php
+
+include 'vendor/autoload.php';
+
+use Async\Spawn\Channeled;
+use Async\Spawn\ChanneledInterface;
+
+$ipc = new Channeled();
+
+echo "Let's play, ";
+
+$process = \spawn(
+    function (ChanneledInterface $channel) {
+        $channel->write('ping');
+        echo $channel->read();
+        echo $channel->read();
+        return \return_in(50, 'The game!');
+    }
+)->signal(\SIGKILL, function ($signal) {
+    echo "the process has been terminated with 'SIGKILL - " . $signal . "' signal!" . \PHP_EOL;
+})->progress(function ($type, $data) use ($ipc) {
+    if ('ping' === $data) {
+        $ipc->send('pang' . \PHP_EOL);
+        $ipc->kill();
+    } elseif (!$ipc->isClosed()) {
+        $ipc->send('pong. ' . \PHP_EOL)
+            ->close();
+    }
+});
+
+$ipc->setHandle($process);
+$result = \spawn_run($process);
+echo \spawn_output($process) . \PHP_EOL;
+echo \spawn_result($process) . \PHP_EOL;
+echo $result . \PHP_EOL;

tests/ChanneledFallbackTest.php

@@ -22,8 +22,7 @@ public function testSimpleChanneled()
             $channel->write('ping');
             echo $channel->read();
             echo $channel->read();
-            returning(1500);
-            return 9;
+            return \return_in(1500, 9);
         }, 10, $ipc)
             ->progress(
                 function ($type, $data) use ($ipc) {