Updates to bring inline with base Coroutine class BC

- drop `fetchOptions/waitOptions` now `await/fetch_await`
- the added `await/fetch_await` combine `fetchOptions()` and `fetch()` into one call
- update tests/example, docblock, docs, required

README.md

@@ -108,7 +108,7 @@ const MULTI_TYPE = 'multipart/form-data';
 const JSON_TYPE = 'application/json';
 const FORM_TYPE = 'application/x-www-form-urlencoded';
 
- /**
+/**
  * This function works similar to coroutine `await()`
  *
  * Takes an `request` instance or `yield`ed coroutine of an request.
@@ -117,15 +117,20 @@ const FORM_TYPE = 'application/x-www-form-urlencoded';
  *
  * - This function needs to be prefixed with `yield`
  */
-yield  \request();
+yield \request();
 
- /**
- * This function works similar to coroutine `gatherOptions()`
+/**
+ * Run awaitable HTTP tasks in the requests set concurrently and block
+ * until the condition specified by count.
+ *
+ * This function works similar to `gatherWait()`.
  *
- * Controls how the `fetch()` function operates.
- * `fetch()` will behave like **Promise** functions `All`, `Some`, `Any` in JavaScript.
+ * Controls how the `wait/fetch` functions operates.
+ * `await()` will behave like **Promise** functions `All`, `Some`, `Any` in JavaScript.
+ *
+ * - This function needs to be prefixed with `yield`
  */
-\fetchOptions($count, $exception, $clearAborted);
+yield \fetch_await($requests, $count, $exception, $clearAborted);
 
 /**
  * This function works similar to coroutine `gather()`

Request/Core.php

@@ -253,22 +253,28 @@ function hyper_clear()
     }
 
     /**
-     * This function works similar to `gatherOptions()`.
+     * Run awaitable HTTP tasks in the requests set concurrently and block until the condition specified by count.
+     *
+     * This function works similar to `gatherWait()`.
      * Controls how the `fetch()` function operates.
-     * `fetch()` will behave like **Promise** functions `All`, `Some`, `Any` in JavaScript.
+     * `fetch_await()` will behave like **Promise** functions `All`, `Some`, `Any` in JavaScript.
+     *
+     * - This function needs to be prefixed with `yield`
      *
+     * @param array $requests
      * @param int $count - Will wait for count to complete, `0` (default) All.
      * @param bool $exception - If `true` (default), immediately propagated
      * to the task that `yield`ed on wait(). Other awaitables will continue to run.
      * - If `false`, exceptions are treated the same as successful response results,
      * and aggregated in the response list.
      * @param bool $clearAborted - If `true` (default), close/cancel/abort remaining result/responses
      *
+     * @return array associative `$httpId` => `$response`
      * @throws \LengthException - If the number of HTTP tasks less than the desired $count.
      */
-    function fetchOptions(int $count = 0, bool $exception = true, bool $clearAborted = true)
+    function fetch_await(array $requests, int $count = 0, bool $exception = true, bool $clearAborted = true)
     {
-        Hyper::waitOptions($count, $exception, $clearAborted);
+        return Hyper::await($requests, $count, $exception, $clearAborted);
     }
 
     /**
@@ -277,10 +283,10 @@ function fetchOptions(int $count = 0, bool $exception = true, bool $clearAborted
      * Will pause current task and continue other tasks until
      * the supplied request HTTP task id's resolve to an response instance.
      *
-     * @return array<ResponseInterface>
-     * @throws \Exception - if not an HTTP task id
-     *
      * - This function needs to be prefixed with `yield`
+     *
+     * @return array associative `$httpId` => `$response`
+     * @throws \Exception - if not an HTTP task id
      */
     function fetch(...$requests)
     {

Request/Hyper.php

@@ -147,12 +147,14 @@ public function logger(): array
     /**
      * @inheritdoc
      */
-    public static function waitOptions(
+    public static function await(
+        array $requests,
         int $count = 0,
         bool $exception = true,
         bool $clearAborted = true
-    ): void {
-        Kernel::gatherOptions($count, $exception, $clearAborted);
+    ) {
+        self::waitController();
+        return Kernel::gatherWait($requests, $count, $exception, $clearAborted);
     }
 
     /**

Request/HyperInterface.php

@@ -26,8 +26,13 @@ public function logger();
     public function withEncoding(): HyperInterface;
 
     /**
-     * Controls how the `wait()` function operates.
+     * Run awaitable HTTP tasks in the requests set concurrently and block until the condition specified by count.
      *
+     * This function works similar to `gatherWait()`.
+     * Controls how the `wait/fetch` functions operates.
+     * `await()` will behave like **Promise** functions `All`, `Some`, `Any` in JavaScript.
+     *
+     * @param array $requests
      * @param int $count - If set, initiate a competitive race between multiple HTTP tasks.
      * - When amount of tasks as completed, the `wait` will return with HTTP task response.
      * - When `0` (default), will wait for all to complete.
@@ -37,13 +42,16 @@ public function withEncoding(): HyperInterface;
      * - If `false`, exceptions are treated the same as successful response results,
      * and aggregated in the response list.
      * @param bool $clearAborted - If `true` (default), close/cancel/abort remaining result/responses
+     * @return array associative `$httpId` => `$response`
      *
-     * @throws \LengthException - If the number of tasks less than the desired $count.
+     * @throws \LengthException - If the number of HTTP tasks less than the desired $count.
      */
-    public static function waitOptions(
+    public static function await(
+        array $requests,
         int $count = 0,
         bool $exception = true,
-        bool $clearAborted = true);
+        bool $clearAborted = true
+    );
 
     /**
      * Run awaitable HTTP tasks in the httpId sequence concurrently.
@@ -57,7 +65,7 @@ public static function waitOptions(
      * @see https://docs.python.org/3.7/library/asyncio-task.html#asyncio.gather
      *
      * @param array $httpId
-     * @return array
+     * @return array associative `$taskId` => `$result`
      *
      * @throws \Exception - if not an HTTP task id
      */

composer.json

@@ -16,7 +16,7 @@
 		"ext-json": "*",
         "symplely/http": "^1.1.0",
         "symplely/logger": "^1.0.9",
-        "symplely/coroutine": "^1.4.3"
+        "symplely/coroutine": "^1.7.0"
     },
     "autoload": {
         "files": [

examples/asyncbenchmark.php

@@ -16,8 +16,7 @@ function taskConcurrentRequests()
 
     print_r($request);
 
-    \fetchOptions(2);
-    $responses = yield \fetch($request);
+    $responses = yield \fetch_await($request, 2);
     print_r($responses);
 }
 

tests/CoreTest.php

@@ -40,8 +40,7 @@ public function task_head($websites)
         }
         $this->assertCount(\count($this->websites), $tasks);
 
-        \fetchOptions(3);
-        $responses = yield \fetch($tasks);
+        $responses = yield \fetch_await($tasks, 3);
 
         global $__uri__;
         $this->assertInstanceOf(\Async\Request\HyperInterface::class, $__uri__);
@@ -172,9 +171,8 @@ public function taskFetchFailSkip()
             (new Request(Request::METHOD_OPTIONS, self::TARGET_URL))->withHeader('Content-Length', '4')
         );
 
-        \fetchOptions(0, false);
-        $responses = yield \fetch($pipedream, $httpBin, $bad);
-        $this->assertCount(2, $responses);
+        $responses = yield \fetch_await([$pipedream, $httpBin, $bad], 0, false);
+        $this->assertInstanceOf(\Throwable::class, $responses[$bad]);
 
         while (!\response_eof('bin')) {
             $echo = yield \response_stream('bin');
@@ -379,8 +377,7 @@ public function taskRequestFailing()
         $this->assertFalse($response);
 
         $this->expectException(\LengthException::class);
-        \fetchOptions(3);
-        $responses = yield \fetch([1]);
+        $responses = yield \fetch_await([1], 3);
         yield \hyper_shutdown();
     }