feature: trackDeferred, deprecating addDeferredToTimer (#43)

* feature: trackDeferred, deprecating addDeferredToTimer
closes #9

* build: php 8.2 compatibility

Author: g105b

composer.json

@@ -28,7 +28,6 @@
 
 	"scripts": {
 		"phpunit": "vendor/bin/phpunit --configuration phpunit.xml",
-		"phpunit:coverage": "XDEBUG_MODE=coverage vendor/bin/phpunit --configuration phpunit.xml --coverage-text",
 		"phpstan": "vendor/bin/phpstan analyse --level 6 src",
 		"phpcs": "vendor/bin/phpcs src --standard=phpcs.xml",
 		"phpmd": "vendor/bin/phpmd src/ text phpmd.xml",

composer.lock

@@ -46,12 +46,37 @@ public function addTimer(Timer $timer):void {
 		$this->timerList [] = $timer;
 	}
 
+	/**
+	 * Track a Deferred within the loop lifecycle without attaching its
+	 * process callbacks to a Timer.
+	 *
+	 * This is useful for libraries that manage their own work scheduling but
+	 * still want the loop to halt when all tracked Deferred objects complete.
+	 */
+	public function trackDeferred(Deferred $deferred):void {
+		if($this->isDeferredTracked($deferred)) {
+			return;
+		}
+
+		$deferred->onComplete(
+			function() use ($deferred) {
+				$this->removeDeferred($deferred);
+			});
+
+		$this->activeDeferred[] = $deferred;
+	}
+
+	/**
+	 * @deprecated Prefer trackDeferred() when only completion tracking is
+	 * required. This method remains for Deferred objects whose process
+	 * callbacks should still be attached to a Timer.
+	 */
 	public function addDeferredToTimer(
 		Deferred $deferred,
 		?Timer $timer = null
 	):void {
 		$timer = $timer ?? $this->timerList[0];
-
+		$this->trackDeferred($deferred);
 		$deferred->onComplete(
 			function() use ($deferred, $timer) {
 				$this->removeDeferredFromTimer(
@@ -63,11 +88,13 @@ function() use ($deferred, $timer) {
 		foreach($deferred->getProcessList() as $function) {
 			$timer->addCallback($function);
 		}
-
-		$this->activeDeferred[] = $deferred;
 	}
 
 
+	/**
+	 * @deprecated Prefer removeDeferred() when no Timer callbacks were attached
+	 * by addDeferredToTimer().
+	 */
 	public function removeDeferredFromTimer(
 		Deferred $deferred,
 		?Timer $timer = null
@@ -77,9 +104,14 @@ public function removeDeferredFromTimer(
 		foreach($deferred->getProcessList() as $function) {
 			$timer->removeCallback($function);
 		}
+		$this->removeDeferred($deferred);
+	}
+
+	public function removeDeferred(Deferred $deferred):void {
 		$activeDeferredIndex = array_search(
 			$deferred,
-			$this->activeDeferred
+			$this->activeDeferred,
+			true
 		);
 		if($activeDeferredIndex !== false) {
 			unset($this->activeDeferred[$activeDeferredIndex]);
@@ -173,4 +205,8 @@ private function executeTimers(TimerOrder $timerOrder):void {
 			$this->trigger($item["timer"]);
 		}
 	}
+
+	private function isDeferredTracked(Deferred $deferred):bool {
+		return array_search($deferred, $this->activeDeferred, true) !== false;
+	}
 }

src/Loop.php

@@ -214,12 +214,30 @@ public function testAddDeferredToTimerSpecificTimer() {
 		$sut->addDeferredToTimer($deferred, $timer2);
 	}
 
+	public function testTrackDeferredDoesNotAttachTimerCallbacks() {
+		$deferredCompleteCallback = null;
+
+		$deferred = self::createMock(Deferred::class);
+		$deferred->expects(self::once())
+			->method("onComplete")
+			->willReturnCallback(function(callable $cb) use(&$deferredCompleteCallback) {
+				$deferredCompleteCallback = $cb;
+			});
+		$deferred->expects(self::never())
+			->method("getProcessList");
+
+		$sut = new Loop();
+		$sut->trackDeferred($deferred);
+
+		self::assertIsCallable($deferredCompleteCallback);
+	}
+
 	public function testHaltWhenAllDeferredComplete() {
 		$deferredCompleteCallback = null;
 		$deferredProcess = function(){};
 
 		$deferred = self::createMock(Deferred::class);
-		$deferred->expects(self::once())
+		$deferred->expects(self::exactly(2))
 			->method("onComplete")
 			->willReturnCallback(function(callable $cb) use(&$deferredCompleteCallback) {
 				$deferredCompleteCallback = $cb;
@@ -254,4 +272,33 @@ public function testHaltWhenAllDeferredComplete() {
 		self::assertIsCallable($deferredCompleteCallback);
 		call_user_func($deferredCompleteCallback);
 	}
+
+	public function testHaltWhenTrackedDeferredComplete() {
+		$deferredCompleteCallback = null;
+
+		$deferred = self::createMock(Deferred::class);
+		$deferred->expects(self::once())
+			->method("onComplete")
+			->willReturnCallback(function(callable $cb) use(&$deferredCompleteCallback) {
+				$deferredCompleteCallback = $cb;
+			});
+		$deferred->expects(self::never())
+			->method("getProcessList");
+
+		/** @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->trackDeferred($deferred);
+		$sut->run();
+
+		self::assertIsCallable($deferredCompleteCallback);
+		call_user_func($deferredCompleteCallback);
+	}
 }