Add reset() to Globals class, test, update docblocks

Spawn/Core.php

@@ -415,12 +415,15 @@ function paralleling(?\Closure $task = null, ?string $include = null, ...$args):
   }
 
   /**
+   * This function is only executed in an actual _running_ `Future` **child-process**.
    * Setup `user defined` global `key => value` pair to be transferred to `Future` **child-process**.
    * - Can `include/require` an additional **file** to execute.
    * - Also an indicator for a `Channel` that it has been started by `child-process` Future.
    *
    * @param string $include additional file to execute
    * @param array|null $keyValue
+   * @internal
+   *
    * @return void
    */
   function paralleling_setup(?string $include = null, ?array $keyValue = null): void
@@ -438,10 +441,13 @@ function paralleling_setup(?string $include = null, ?array $keyValue = null): vo
 
   /**
    * Start the `Future` process and wait to terminate, and return any results.
+   * - Note this should only be executed for local testing only.
    *
    * @param FutureInterface $future
    * @param boolean $displayOutput
    * @return mixed
+   *
+   * @internal
    */
   function spawn_run(FutureInterface $future, bool $displayOutput = false)
   {
@@ -450,9 +456,12 @@ function spawn_run(FutureInterface $future, bool $displayOutput = false)
 
   /**
    * Wait for a **pool** of **Parallel** `Future` processes to terminate, and return any results.
+   * - Note this should only be executed for local testing only.
    *
    * @param ParallelInterface $futures
    * @return mixed
+   *
+   * @internal
    */
   function spawn_wait(ParallelInterface $futures)
   {

Spawn/FutureInterface.php

@@ -39,13 +39,16 @@ public function restart(): FutureInterface;
 
   /**
    * Start the `Future` process and wait to terminate.
+   * - Note this should only be executed for local testing only.
    *
    * @param bool $useYield - should we use generator callback functions
+   * @return mixed
    */
   public function run(bool $useYield = false);
 
   /**
    * Return an generator that can start the `Future` process and wait to terminate.
+   * - Note this should only be executed for local testing only.
    *
    * @return \Generator
    */
@@ -64,9 +67,12 @@ public function Kill();
 
   /**
    * Waits for all processes to terminate.
+   * - Note this should only be executed for local testing only.
    *
    * @param int $waitTimer - Halt time in micro seconds
    * @param bool $useYield - should we use generator callback functions
+   *
+   * @return mixed
    */
   public function wait($waitTimer = 1000, bool $useYield = false);
 

Spawn/Globals.php

@@ -4,6 +4,11 @@
 
 namespace Async\Spawn;
 
+/**
+ * For passing/controlling how a Future `child-process` operate as **ext-parallel** like.
+ *
+ * @internal
+ */
 class Globals
 {
   /**
@@ -17,6 +22,7 @@ class Globals
 
   /**
    * Returns an array of **Future** `user defined` *global* variables.
+   * @internal
    *
    * @return array[]|null
    */
@@ -25,17 +31,50 @@ public static function get(): ?array
     return self::$defined;
   }
 
+  /**
+   * Setup any returned `user defined` *global* variables from a finished **Future**.
+   *
+   * @param string|null $key
+   * @param mixed $value
+   * @internal
+   *
+   * @return void
+   */
   public static function set(?string $key, $value): void
   {
     if (isset($key))
       self::$defined[$key] = $value;
   }
 
+  /**
+   * Clear out all **Future** `user defined` *global* variables and indicator.
+   * @internal
+   *
+   * @return void
+   */
+  public static function reset(): void
+  {
+    self::$defined = null;
+    self::$isChannel = false;
+  }
+
+  /**
+   * Set indicator for a `Channel` started in a **ext-parallel** like `child-process` Future.
+   * @internal
+   *
+   * @return void
+   */
   public static function channelling(): void
   {
     self::$isChannel = true;
   }
 
+  /**
+   * Check if `Channel` started in a **ext-parallel** like `child-process` Future.
+   * @internal
+   *
+   * @return boolean
+   */
   public static function isChannelling(): bool
   {
     return self::$isChannel;

Spawn/ParallelInterface.php

@@ -75,9 +75,10 @@ public function retry(FutureInterface $future = null): FutureInterface;
 
   /**
    * Wait for a **pool** of `Future` processes to terminate, and return any results.
+   * - Note this should only be executed for local testing only.
    *
    * @param ParallelInterface $futures
-   * @return mixed
+   * @return array
    */
   public function wait(): array;
 

tests/SpawnTest.php

@@ -355,17 +355,20 @@ public function setGlobal()
   {
     global $test;
     $test = 100;
+    $this->assertFalse(Globals::isChannelling());
     paralleling_setup(null, ['test' => 2, 'other' => 'foo']);
-    $this->assertEquals($GLOBALS['test'], 2);
-    $test = 4;
-    $this->assertEquals($GLOBALS['test'], 4);
+    $this->assertTrue(Globals::isChannelling());
   }
 
   public function testSetGetGlobals()
   {
     global $test;
     $this->setGlobal();
     $this->assertEquals($GLOBALS['other'], 'foo');
-    $this->assertEquals($test, 4);
+    $this->assertEquals($test, 2);
+    Globals::reset();
+    $global = Globals::get();
+    $this->assertNull($global);
+    $this->assertFalse(Globals::isChannelling());
   }
 }