Merge pull request #4 from ace411/v0.x

v0.2.2 fixes

Author: ace411

README.md

@@ -70,15 +70,19 @@ $exec = Async::create()
 
 The examples directory contains more nuanced uses of the library that I recommend you check out.
 
-## Limitation
+## Limitations
 
-`asyncify` is no panacea, but is capable of asynchronously executing a plethora of blocking calls. As presently constituted, the library is incapable of processing inputs and outputs that cannot be serialized.
+- `asyncify` is no panacea, but is capable of asynchronously executing a plethora of blocking calls. As presently constituted, the library is **incapable of processing inputs and outputs that cannot be serialized**. Its quintessential asynchronous function application primitive - `call()` - works almost exclusively with string encodings of native language functions and lambdas imported via an autoloading mechanism.
+
+- The library cannot parse closures. All executable arbitrary code should be emplaced in a string whose sole constituent is an immediately invokable anonymous function the format of which is `(function (...$args) { /* signature */ })`.
 
 ## API Reference
 
 ### Object
 
 ```php
+namespace Chemem\Asyncify;
+
 class Async {
 
   /* Methods */
@@ -94,6 +98,8 @@ class Async {
 ### Function
 
 ```php
+namespace Chemem\Asyncify;
+
 call ( string $func [, array $args [, ?string $autoload = null [, ?React\EventLoop\LoopInterface $args = null ] ] ] ) : React\Promise\PromiseInterface;
 ```
 

composer.json

@@ -14,7 +14,7 @@
     "php": ">=7.2",
     "chemem/bingo-functional": "~2",
     "react/child-process": "~0",
-    "react/promise-stream": "~1"
+    "react/promise": "~2"
   },
   "require-dev": {
     "ergebnis/composer-normalize": "~2",

src/Async.php

@@ -63,6 +63,20 @@ public static function create(?string $autoload = null, ?LoopInterface $loop = n
    * @param string $function
    * @param array $args
    * @return PromiseInterface
+   * @example
+   *
+   * $async = Async::create('/path/to/autoload.php');
+   * $res = $async
+   *  ->call('file_get_contents', ['path/to/file'])
+   *  ->then(
+   *    function (string $contents) {
+   *      echo $contents . PHP_EOL;
+   *    },
+   *    function (Throwable $err) {
+   *      echo $err->getMessage() . PHP_EOL;
+   *    }
+   *  )
+   * => file_get_contents(/path/to/file): Failed to open stream: No such file or directory
    */
   public function call(string $function, array $args): PromiseInterface
   {

src/call.php

@@ -25,6 +25,18 @@
  *
  * @param mixed ...$args
  * @return mixed
+ * @example
+ *
+ * call('file_get_contents', ['path/to/file'])
+ *  ->then(
+ *    function (string $contents) {
+ *      echo $contents . PHP_EOL;
+ *    },
+ *    function (Throwable $err) {
+ *      echo $err->getMessage() . PHP_EOL;
+ *    }
+ *  )
+ * => file_get_contents(/path/to/file): Failed to open stream: No such file or directory
  */
 function call(...$args)
 {

src/internal/asyncify.php

@@ -35,6 +35,18 @@
  * @param string|null $autoload
  * @param LoopInterface|null $loop
  * @return PromiseInterface
+ * @example
+ *
+ * $data = asyncify('file_get_contents', ['path/to/file'])
+ *  ->then(
+ *    function (string $contents) {
+ *      echo $contents . PHP_EOL;
+ *    },
+ *    function (Throwable $err) {
+ *      echo $err->getMessage() . PHP_EOL;
+ *    }
+ *  )
+ * => file_get_contents(/path/to/file): Failed to open stream: No such file or directory
  */
 function asyncify(
   string $function,

src/internal/constants.php

@@ -18,7 +18,7 @@
 const PHP_EXECUTABLE_TEMPLATE = <<<'PHP'
 function handleException(Throwable $exception): void
 {
-  echo "Exception: " . $exception->getMessage();
+  echo $exception->getMessage();
 }
 function handleError(...$args)
 {
@@ -34,7 +34,11 @@ function (...$args) {
         return %s(...$args);
       },
       function ($err) {
-        return new \Exception("Exception: " . $err->getMessage());
+        return new \Exception(
+          $err->getMessage(),
+          $err->getCode(),
+          $err->getPrevious()
+        );
       }
     )(...\unserialize(\base64_decode("%s")))
   )

src/internal/proc.php

@@ -14,11 +14,9 @@
 
 use React\ChildProcess\Process;
 use React\EventLoop\LoopInterface;
+use React\Promise\Deferred;
 use React\Promise\PromiseInterface;
 
-use function React\Promise\reject;
-use function React\Promise\Stream\buffer;
-
 const proc = __NAMESPACE__ . '\\proc';
 
 /**
@@ -33,19 +31,64 @@
  * @return PromiseInterface
  * @example
  *
- * proc('php -r "echo 12;"')
- * => object(React\Promise\Promise) {}
+ * proc('php -r "echo 12 . PHP_EOL;"')
+ *  ->then(
+ *    function ($result) {
+ *      echo $result;
+ *    }
+ *  )
+ * => 12
  */
 function proc(string $process, ?LoopInterface $loop = null): PromiseInterface
 {
-  $proc = new Process($process);
+  $proc   = new Process($process);
+  $result = new Deferred();
   $proc->start($loop);
 
   if (!$proc->stdout->isReadable()) {
-    return reject(
-      new \Exception(\sprintf('Could not process %s', $process))
+    $result->reject(
+      new \Exception(
+        \sprintf('Could not process "%s"', $process)
+      )
     );
+
+    return $result;
   }
 
-  return buffer($proc->stdout);
+  $proc->stdout->on(
+    'data',
+    function ($chunk) use (&$result) {
+      $result->resolve($chunk);
+    }
+  );
+
+  // reject promise in the event of failure
+  $proc->stdout->on(
+    'error',
+    function (\Throwable $err) use (&$result, &$proc) {
+      $result->reject($err);
+    }
+  );
+
+  // handle successful closure of the process stream
+  $proc->stdout->on(
+    'end',
+    function () use (&$result) {
+      $result->resolve(true);
+    }
+  );
+
+  // handle unsuccessful closure of process stream
+  $proc->stdout->on(
+    'close',
+    function () use (&$result, $process) {
+      $result->reject(
+        new \Exception(
+          \sprintf('Closed process "%s"', $process)
+        )
+      );
+    }
+  );
+
+  return $result->promise();
 }

tests/AsyncTest.php

@@ -24,14 +24,14 @@ public function asyncifyProvider(): array
           '(function (...$args) { if (!\is_file($args[0])) { throw new \Exception("Could not find file: " . $args[0]); } return \file_get_contents($file); })',
           [12],
         ],
-        'Exception: Could not find file: 12',
+        'Could not find file: 12',
       ],
       // native PHP function
       [
         ['file_get_contents', ['foo.txt']],
         concat(
           ' ',
-          'Exception: file_get_contents(foo.txt):',
+          'file_get_contents(foo.txt):',
           PHP_VERSION_ID >= 80000 ? 'Failed' : 'failed',
           'to open stream: No such file or directory'
         ),
@@ -41,7 +41,7 @@ public function asyncifyProvider(): array
         ['file_get_contents', []],
         concat(
           ' ',
-          'Exception: file_get_contents() expects at least 1',
+          'file_get_contents() expects at least 1',
           PHP_VERSION_ID >= 80000 ? 'argument,' : 'parameter,',
           '0 given'
         ),
@@ -52,7 +52,7 @@ public function asyncifyProvider(): array
           '(function ($file) { if (!\is_file($file)) { trigger_error("Could not find file " . $file); } return \file_get_contents($file); })',
           ['foo.txt'],
         ],
-        'Exception: Could not find file foo.txt',
+        'Could not find file foo.txt',
       ],
       // check if objects can be passed
       [

tests/Internal/InternalTest.php

@@ -20,7 +20,7 @@ public function procProvider(): array
       // php commandline process
       [['php -r \'echo "foo";\''], 'foo'],
       // invalid input
-      [['kat --foo'], ''],
+      [['kat --foo'], 'Closed process "kat --foo"'],
     ];
   }