Use php.gt/promise for Promise implementation

Author: Greg Bowler

example/03-slow-file-reads.php example/03-promise.phpexample/03-slow-file-reads.php renamed to example/03-promise.php

@@ -1,20 +1,20 @@
 <?php
 /**
- * This example counts the number of vowels in example1.txt and the number of
- * consonants in example2.txt, showing how concurrent slow file reads can
- * use Promises to defer work, with a future callback when the work is complete.
+ * This example counts the number of vowels and the number of consonants
+ * in example.txt, showing how concurrent slow file reads can use Promises
+ * to defer work, with a future callback when the work is complete.
  *
- * A PeriodicLoop is used with a long period and the file reading code
- * is done one byte at a time, to simulate a slow connection.
+ * A PeriodicLoop is used with a purposefully long period with the file
+ * reading code being done one byte at a time, to simulate a slow connection.
  *
  * Note: This is an example wrapped in a class, showing an example of how a
  * framework could offer promise-driven filesystem functionality.
  */
 
 use Gt\Async\Loop;
-use Gt\Async\Promise\Deferred;
-use Gt\Async\Promise\Promise;
 use Gt\Async\Timer\PeriodicTimer;
+use Gt\Promise\Deferred;
+use Gt\Promise\PromiseInterface;
 
 require("../vendor/autoload.php");
 
@@ -35,10 +35,10 @@ public function setLoop(Loop $loop):void {
 
 // This is the public function that will be called, returning a Promise that
 // represents the completed work.
-	public function countCharacters(string $charMap):Promise {
+	public function countCharacters(string $charMap):PromiseInterface {
 // A new Deferred is created to assign this class's specific process function.
 		$this->deferred = new Deferred();
-		$this->deferred->addProcessFunction(
+		$this->deferred->addProcess(
 			fn() => $this->processNextCharacter($charMap)
 		);
 // The Deferred is added to the Loop's default timer, which will call its
@@ -52,9 +52,7 @@ public function countCharacters(string $charMap):Promise {
 // This functions is called by the Deferred, as the Deferred is invoked by the
 // background Loop. It must not do much work per call, as to not block the
 // execution of other deferred tasks.
-	public function processNextCharacter(string $charMap):void {
-// TODO: Nice. Got this far. Now it's time to finish Promise implementation,
-// and then we can complete this example's functionality here.
+	private function processNextCharacter(string $charMap):void {
 		if(!isset($this->characterCount)) {
 			$this->characterCount = 0;
 		}
@@ -80,24 +78,40 @@ public function processNextCharacter(string $charMap):void {
 // second. This is actually quite slow, used to illustrate how concurrent tasks
 // will behave.
 $timer = new PeriodicTimer(0.1, true);
+$timer->addCallback(function() {
+	echo ".";
+});
+
+// This loop will be called to run forever by the run() function at the bottom
+// of this file, but here we are setting the loop to halt if all internal
+// Deferred objects complete.
 $loop = new Loop();
 $loop->addTimer($timer);
 $loop->haltWhenAllDeferredComplete(true);
 
+// Create the example classes to slowly loop over the characters of the file.
 $reader1 = new SlowFileReader("example.txt");
 $reader1->setLoop($loop);
 $reader2 = new SlowFileReader("example.txt");
 $reader2->setLoop($loop);
 
-$reader1->countCharacters("aeiou");
-//->then(function(int $numVowels):void {
-//	echo "Example text has $numVowels vowels.", PHP_EOL;
-//});
-//
-//$reader2->countCharacters("bcdfghjklmnpqrstvwxyz")
-//->then(function(int $numConsonants):void {
-//	echo "Example text has $numConsonants consonants.", PHP_EOL;
-//});
+// The countCharacters function returns a Promise, meaning it will not actually
+// undertake any work itself, but will resolve the promise when the work
+// completes. The work is undertaken by the Deferred object, which is triggered
+// by the Loop's timers.
+$reader1->countCharacters("aeiou")
+->then(function(int $numVowels):void {
+	echo "Example text has $numVowels vowels.", PHP_EOL;
+});
+
+// Another Promise can be added, so their Deferred's work is undertaken
+// concurrently.
+$reader2->countCharacters("bcdfghjklmnpqrstvwxyz")
+->then(function(int $numConsonants):void {
+	echo "Example text has $numConsonants consonants.", PHP_EOL;
+});
 
+// Here we execute the loop, which has been set to halt when all Deferred
+// objects complete.
 $loop->run();
 echo "Complete!", PHP_EOL;

src/Loop.php

@@ -1,9 +1,9 @@
 <?php
 namespace Gt\Async;
 
-use Gt\Async\Promise\Deferred;
 use Gt\Async\Timer\Timer;
 use Gt\Async\Timer\TimerOrder;
+use Gt\Promise\Deferred;
 
 /**
  * The core event loop class, used to dispatch all events via different added
@@ -25,6 +25,8 @@ class Loop {
 	private bool $haltWhenAllDeferredComplete;
 	/** @var Deferred[] */
 	private array $activeDeferred;
+	/** @var callable[] */
+	private array $haltCallbackList;
 
 	public function __construct() {
 		$this->timerList = [];
@@ -37,6 +39,7 @@ public function __construct() {
 		};
 		$this->haltWhenAllDeferredComplete = false;
 		$this->activeDeferred = [];
+		$this->haltCallbackList = [];
 	}
 
 	public function addTimer(Timer $timer):void {
@@ -49,28 +52,29 @@ public function addDeferredToTimer(
 	):void {
 		$timer = $timer ?? $this->timerList[0];
 
-		foreach($deferred->getProcessFunctionArray() as $function) {
-			$timer->addCallback($function);
-		}
-		$timer->addCallback(function() use($deferred, $timer) {
-			if(!$deferred->isActive()) {
+		$deferred->addCompleteCallback(
+			function() use ($deferred, $timer) {
 				$this->removeDeferredFromTimer(
 					$deferred,
 					$timer
 				);
-			}
-		});
+			});
+
+		foreach($deferred->getProcessList() as $function) {
+			$timer->addCallback($function);
+		}
 
 		$this->activeDeferred[] = $deferred;
 	}
 
+
 	public function removeDeferredFromTimer(
 		Deferred $deferred,
 		Timer $timer = null
 	):void {
 		$timer = $timer ?? $this->timerList[0];
 
-		foreach($deferred->getProcessFunctionArray() as $function) {
+		foreach($deferred->getProcessList() as $function) {
 			$timer->removeCallback($function);
 		}
 		$activeDeferredIndex = array_search(
@@ -107,6 +111,20 @@ public function run(bool $forever = true):void {
 
 	public function halt():void {
 		$this->forever = false;
+
+		foreach($this->haltCallbackList as $callback) {
+			call_user_func($callback);
+		}
+	}
+
+	public function haltWhenAllDeferredComplete(
+		bool $shouldHalt = true
+	):void {
+		$this->haltWhenAllDeferredComplete = $shouldHalt;
+	}
+
+	public function addHaltCallback(callable $callback):void {
+		array_push($this->haltCallbackList, $callback);
 	}
 
 	public function getTriggerCount():int {
@@ -123,10 +141,6 @@ public function waitUntil(float $waitUntilEpoch):void {
 		call_user_func($this->sleepFunction, $diff);
 	}
 
-	public function haltWhenAllDeferredComplete(bool $halt):void {
-		$this->haltWhenAllDeferredComplete = $halt;
-	}
-
 	private function triggerNextTimers():int {
 		$timerOrder = new TimerOrder($this->timerList);
 

src/Timer/Timer.php

@@ -1,8 +1,6 @@
 <?php
 namespace Gt\Async\Timer;
 
-use Gt\Async\Asyncable;
-
 /**
  * Represents one or more trigger times. If the tick function is called when
  * a timer is due, it will execute the timer's callback(s).
@@ -29,11 +27,10 @@ public function setTimeFunction(callable $callable):void {
 	}
 
 	public function addCallback(callable $callback):void {
-		$this->callbackList[] = $callback;
+		array_push($this->callbackList, $callback);
 	}
 
 	public function removeCallback(callable $callback):void {
-// TODO: Throw exception if it doesn't exist.
 		$callbackIndex = array_search($callback, $this->callbackList);
 		unset($this->callbackList[$callbackIndex]);
 	}

test/phpunit/LoopTest.php

@@ -3,7 +3,10 @@
 
 use Gt\Async\Loop;
 use Gt\Async\Timer\Timer;
+use Gt\Promise\Deferred;
+use PHPUnit\Framework\MockObject\MockObject;
 use PHPUnit\Framework\TestCase;
+use stdClass;
 
 class LoopTest extends TestCase {
 	public function testRunWithNoTimer() {
@@ -170,4 +173,85 @@ public function testSleepActuallyDelays() {
 			round($endEpoch, 2)
 		);
 	}
+
+	public function testAddDeferredToTimerNoTimerPassed() {
+		$callback = function(){};
+
+		$timer = self::createMock(Timer::class);
+		$timer->expects(self::once())
+			->method("addCallback")
+			->with(self::identicalTo($callback));
+
+		$deferred = self::createMock(Deferred::class);
+		$deferred->expects(self::once())
+			->method("getProcessList")
+			->willReturn([$callback]);
+
+		$sut = new Loop();
+		$sut->addTimer($timer);
+		$sut->addDeferredToTimer($deferred);
+	}
+
+	public function testAddDeferredToTimerSpecificTimer() {
+		$callback = function(){};
+
+		$timer1 = self::createMock(Timer::class);
+		$timer1->expects(self::never())
+			->method("addCallback");
+		$timer2 = self::createMock(Timer::class);
+		$timer2->expects(self::once())
+			->method("addCallback")
+			->with(self::identicalTo($callback));
+
+		$deferred = self::createMock(Deferred::class);
+		$deferred->expects(self::once())
+			->method("getProcessList")
+			->willReturn([$callback]);
+
+		$sut = new Loop();
+		$sut->addTimer($timer1);
+		$sut->addTimer($timer2);
+		$sut->addDeferredToTimer($deferred, $timer2);
+	}
+
+	public function testHaltWhenAllDeferredComplete() {
+		$deferredCompleteCallback = null;
+		$deferredProcess = function(){};
+
+		$deferred = self::createMock(Deferred::class);
+		$deferred->expects(self::once())
+			->method("addCompleteCallback")
+			->willReturnCallback(function(callable $cb) use(&$deferredCompleteCallback) {
+				$deferredCompleteCallback = $cb;
+			});
+		$deferred->expects(self::exactly(2))
+			->method("getProcessList")
+			->willReturn([$deferredProcess]);
+
+		$timer = self::createMock(Timer::class);
+		$timer->expects(self::once())
+			->method("addCallback")
+			->with(self::identicalTo($deferredProcess));
+		$timer->expects(self::once())
+			->method("removeCallback")
+			->with(self::identicalTo($deferredProcess));
+
+		/** @var MockObject|callable $haltCallback */
+		$haltCallback = self::getMockBuilder(stdClass::class)
+			->addMethods(["__invoke"])
+			->getMock();
+		$haltCallback->expects(self::once())
+			->method("__invoke");
+
+		$sut = new Loop();
+		$sut->addHaltCallback($haltCallback);
+		$sut->haltWhenAllDeferredComplete();
+		$sut->addTimer($timer);
+		$sut->addDeferredToTimer($deferred, $timer);
+		$sut->run();
+
+// Simulate the Deferred object calling its complete callback:
+		self::assertIsCallable($deferredCompleteCallback);
+		call_user_func($deferredCompleteCallback);
+	}
 }

test/phpunit/Promise/PromiseTest.php

@@ -127,4 +127,25 @@ public function testAddCallbackTriggeredAtCorrectTime() {
 		$sut->tick(); // 1006
 		self::assertEquals(4, $callbackCount);
 	}
+
+	public function testRemoveCallback() {
+		$exampleCallbackCount = 0;
+		$exampleCallback = function() use(&$exampleCallbackCount) {
+			$exampleCallbackCount++;
+		};
+
+		$epoch = 1000;
+		$sut = new IndividualTimer();
+		$sut->addTriggerTime($epoch);
+		$sut->addTriggerTime($epoch + 1);
+		$sut->setTimeFunction(function() use(&$epoch) {
+			return $epoch++;
+		});
+
+		$sut->addCallback($exampleCallback);
+		$sut->tick();
+		$sut->removeCallback($exampleCallback);
+		$sut->tick();
+		self::assertEquals(1, $exampleCallbackCount);
+	}
 }