Generalize asynchronous events

src/event/AsyncEvent.php

@@ -0,0 +1,53 @@
+<?php
+
+/*
+ *
+ *  ____            _        _   __  __ _                  __  __ ____
+ * |  _ \ ___   ___| | _____| |_|  \/  (_)_ __   ___      |  \/  |  _ \
+ * | |_) / _ \ / __| |/ / _ \ __| |\/| | | '_ \ / _ \_____| |\/| | |_) |
+ * |  __/ (_) | (__|   <  __/ |_| |  | | | | | |  __/_____| |  | |  __/
+ * |_|   \___/ \___|_|\_\___|\__|_|  |_|_|_| |_|\___|     |_|  |_|_|
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * @author PocketMine Team
+ * @link http://www.pocketmine.net/
+ *
+ *
+ */
+
+declare(strict_types=1);
+
+namespace pocketmine\event;
+
+use pocketmine\promise\Promise;
+use pocketmine\utils\ObjectSet;
+
+/**
+ * This interface is implemented by an Event subclass if and only if it can be called asynchronously.
+ *
+ * Used with {@see AsyncEventTrait} to provide a way to call an event asynchronously.
+ * When an event is called asynchronously, the event handlers are called by priority level.
+ * When all the promises of a priority level have been resolved, the next priority level is called.
+ */
+interface AsyncEvent{
+	/**
+	 * Add a promise to the set of promises that will be awaited before the next priority level is called.
+	 *
+	 * @phpstan-param Promise<null> $promise
+	 */
+	public function addPromise(Promise $promise) : void;
+
+	/**
+	 * Be prudent, calling an event asynchronously can produce unexpected results.
+	 * During the execution of the event, the server, the player and the event context may have changed state.
+	 *
+	 * @phpstan-param ObjectSet<Promise<null>> $promiseSet
+	 *
+	 * @phpstan-return Promise<null>
+	 */
+	public static function callAsync(AsyncEvent&Event $event, ObjectSet $promiseSet) : Promise;
+}

src/event/AsyncEventTrait.php

@@ -0,0 +1,84 @@
+<?php
+
+/*
+ *
+ *  ____            _        _   __  __ _                  __  __ ____
+ * |  _ \ ___   ___| | _____| |_|  \/  (_)_ __   ___      |  \/  |  _ \
+ * | |_) / _ \ / __| |/ / _ \ __| |\/| | | '_ \ / _ \_____| |\/| | |_) |
+ * |  __/ (_) | (__|   <  __/ |_| |  | | | | | |  __/_____| |  | |  __/
+ * |_|   \___/ \___|_|\_\___|\__|_|  |_|_|_| |_|\___|     |_|  |_|_|
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * @author PocketMine Team
+ * @link http://www.pocketmine.net/
+ *
+ *
+ */
+
+declare(strict_types=1);
+
+namespace pocketmine\event;
+
+use pocketmine\promise\Promise;
+use pocketmine\promise\PromiseResolver;
+use pocketmine\utils\ObjectSet;
+use function array_shift;
+use function count;
+
+trait AsyncEventTrait {
+	/** @phpstan-var ObjectSet<Promise<null>> */
+	private ObjectSet $promises;
+
+	/**
+	 * @phpstan-param ObjectSet<Promise<null>>|null $promises
+	 */
+	private function initializePromises(?ObjectSet &$promises) : void{
+		$promises ??= new ObjectSet();
+		$this->promises = $promises;
+	}
+
+	public function addPromise(Promise $promise) : void{
+		if(!isset($this->promises)){
+			throw new \RuntimeException("Cannot add promises, be sure to initialize the promises set in the constructor");
+		}
+		$this->promises->add($promise);
+	}
+
+	final public static function callAsync(AsyncEvent&Event $event, ObjectSet $promiseSet) : Promise{
+		$event->checkMaxDepthCall();
+
+		/** @phpstan-var PromiseResolver<null> $globalResolver */
+		$globalResolver = new PromiseResolver();
+
+		$callable = function(int $priority) use ($event, $promiseSet) : Promise{
+			$handlers = HandlerListManager::global()->getListFor(static::class)->getListenersByPriority($priority);
+			$event->callHandlers($handlers);
+
+			$array = $promiseSet->toArray();
+			$promiseSet->clear();
+
+			return Promise::all($array);
+		};
+
+		$priorities = EventPriority::ALL;
+		$testResolve = function () use (&$testResolve, &$priorities, $callable, $globalResolver){
+			if(count($priorities) === 0){
+				$globalResolver->resolve(null);
+			}else{
+				$callable(array_shift($priorities))->onCompletion(function() use ($testResolve) : void{
+					$testResolve();
+				}, function () use ($globalResolver) {
+					$globalResolver->reject();
+				});
+			}
+		};
+
+		$testResolve();
+
+		return $globalResolver->getPromise();
+	}
+}

src/event/Event.php

@@ -47,15 +47,30 @@ final public function getEventName() : string{
 	 * @throws \RuntimeException if event call recursion reaches the max depth limit
 	 */
 	public function call() : void{
+		$this->checkMaxDepthCall();
+		$this->callHandlers(null);
+	}
+
+	/**
+	 * @internal used by AsyncEventTrait and Event
+	 */
+	final protected function checkMaxDepthCall() : void{
 		if(self::$eventCallDepth >= self::MAX_EVENT_CALL_DEPTH){
 			//this exception will be caught by the parent event call if all else fails
 			throw new \RuntimeException("Recursive event call detected (reached max depth of " . self::MAX_EVENT_CALL_DEPTH . " calls)");
 		}
+	}
 
+	/**
+	 * @param RegisteredListener[]|null $handlers
+	 *
+	 * @internal used by AsyncEventTrait and Event
+	 */
+	final protected function callHandlers(?array $handlers) : void{
 		$timings = Timings::getEventTimings($this);
 		$timings->startTiming();
 
-		$handlers = HandlerListManager::global()->getHandlersFor(static::class);
+		$handlers = $handlers ?? HandlerListManager::global()->getHandlersFor(static::class);
 
 		++self::$eventCallDepth;
 		try{

src/promise/Promise.php

@@ -23,10 +23,11 @@
 
 namespace pocketmine\promise;
 
+use function count;
 use function spl_object_id;
 
 /**
- * @phpstan-template TValue
+ * @phpstan-template-covariant TValue
  */
 final class Promise{
 	/**
@@ -52,4 +53,54 @@ public function onCompletion(\Closure $onSuccess, \Closure $onFailure) : void{
 	public function isResolved() : bool{
 		return $this->shared->resolved;
 	}
+
+	/**
+	 * Returns a promise that will resolve only once all the Promises in
+	 * `$promises` have resolved. The resolution value of the returned promise
+	 * will be an array containing the resolution values of each Promises in
+	 * `$promises` indexed by the respective Promises' array keys.
+	 *
+	 * @template TPromiseValue
+	 * @phpstan-param Promise<TPromiseValue>[] $promises
+	 *
+	 * @phpstan-return Promise<array<int, TPromiseValue>>
+	 */
+	public static function all(array $promises) : Promise {
+		/** @phpstan-var PromiseResolver<array<int, TPromiseValue>> $resolver */
+		$resolver = new PromiseResolver();
+		$values = [];
+		$toResolve = count($promises);
+		$continue = true;
+
+		foreach($promises as $key => $promise){
+			$values[$key] = null;
+
+			$promise->onCompletion(
+				function(mixed $value) use ($resolver, $key, &$toResolve, &$continue, &$values) : void{
+					$values[$key] = $value;
+
+					if(--$toResolve === 0 && $continue){
+						$resolver->resolve($values);
+					}
+				},
+				function() use ($resolver, &$continue) : void{
+					if($continue){
+						$continue = false;
+						$resolver->reject();
+					}
+				}
+			);
+
+			if(!$continue){
+				break;
+			}
+		}
+
+		if($toResolve === 0){
+			$continue = false;
+			$resolver->resolve($values);
+		}
+
+		return $resolver->getPromise();
+	}
 }

tests/phpstan/configs/actual-problems.neon

@@ -1205,3 +1205,8 @@ parameters:
 			count: 1
 			path: ../../phpunit/scheduler/AsyncPoolTest.php
 
+		-
+			message: "#^Right side of && is always true\\.$#"
+			count: 1
+			path: ../../../src/promise/Promise.php
+