Generalize asynchronous events

src/event/AsyncEvent.php

@@ -0,0 +1,43 @@
+<?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;
+
+/**
+ * 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{
+	/**
+	 * 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-return Promise<null>
+	 */
+	public function callAsync() : Promise;
+}

src/event/AsyncEventDelegate.php

@@ -0,0 +1,131 @@
+<?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;
+
+final class AsyncEventDelegate extends Event{
+	/** @phpstan-var ObjectSet<Promise<null>> $promises */
+	private ObjectSet $promises;
+
+	public function __construct(
+		private AsyncEvent&Event $event
+	){
+		$this->promises = new ObjectSet();
+	}
+
+	/**
+	 * @phpstan-return Promise<null>
+	 */
+	public function callAsync() : Promise{
+		$this->promises->clear();
+		return $this->callDepth($this->callAsyncDepth(...));
+	}
+
+	/**
+	 * @phpstan-return Promise<null>
+	 */
+	private function callAsyncDepth() : Promise{
+		/** @phpstan-var PromiseResolver<null> $globalResolver */
+		$globalResolver = new PromiseResolver();
+
+		$priorities = EventPriority::ALL;
+		$testResolve = function () use (&$testResolve, &$priorities, $globalResolver){
+			if(count($priorities) === 0){
+				$globalResolver->resolve(""); // TODO: see #6110
+			}else{
+				$this->callPriority(array_shift($priorities))->onCompletion(function() use ($testResolve) : void{
+					$testResolve();
+				}, function () use ($globalResolver) {
+					$globalResolver->reject();
+				});
+			}
+		};
+
+		$testResolve();
+
+		return $globalResolver->getPromise();
+	}
+
+	/**
+	 * @phpstan-return Promise<null>
+	 */
+	private function callPriority(int $priority) : Promise{
+		$handlers = HandlerListManager::global()->getListFor($this->event::class)->getListenersByPriority($priority);
+
+		/** @phpstan-var PromiseResolver<null> $resolver */
+		$resolver = new PromiseResolver();
+
+		$nonConcurrentHandlers = [];
+		foreach($handlers as $registration){
+			if($registration instanceof RegisteredAsyncListener){
+				if($registration->canBeCallConcurrently()){
+					$this->promises->add($registration->callAsync($this->event));
+				}else{
+					$nonConcurrentHandlers[] = $registration;
+				}
+			}else{
+				$registration->callEvent($this->event);
+			}
+		}
+
+		$testResolve = function() use (&$nonConcurrentHandlers, &$testResolve, $resolver){
+			if(count($nonConcurrentHandlers) === 0){
+				$this->waitForPromises()->onCompletion(function() use ($resolver){
+					$resolver->resolve(""); // TODO: see #6110
+				}, function() use ($resolver){
+					$resolver->reject();
+				});
+			}else{
+				$this->waitForPromises()->onCompletion(function() use (&$nonConcurrentHandlers, $testResolve){
+					$handler = array_shift($nonConcurrentHandlers);
+					if($handler instanceof RegisteredAsyncListener){
+						$this->promises->add($handler->callAsync($this->event));
+					}
+					$testResolve();
+				}, function() use ($resolver) {
+					$resolver->reject();
+				});
+			}
+		};
+
+		$testResolve();
+
+		return $resolver->getPromise();
+	}
+
+	/**
+	 * @phpstan-return Promise<array<int, null>>
+	 */
+	private function waitForPromises() : Promise{
+		$array = $this->promises->toArray();
+		$this->promises->clear();
+
+		return Promise::all($array);
+	}
+}

src/event/AsyncEventTrait.php

@@ -0,0 +1,40 @@
+<?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;
+
+trait AsyncEventTrait {
+	private AsyncEventDelegate $delegate;
+
+	/**
+	 * @phpstan-return Promise<null>
+	 */
+	final public function callAsync() : Promise{
+		if(!isset($this->delegate)){
+			$this->delegate = new AsyncEventDelegate($this);
+		}
+		return $this->delegate->callAsync();
+	}
+}

src/event/Event.php

@@ -47,6 +47,21 @@ final public function getEventName() : string{
 	 * @throws \RuntimeException if event call recursion reaches the max depth limit
 	 */
 	public function call() : void{
+		$this->callDepth(function(){
+			$handlers = HandlerListManager::global()->getHandlersFor(static::class);
+
+			foreach($handlers as $registration){
+				$registration->callEvent($this);
+			}
+		});
+	}
+
+	/**
+	 * @template T
+	 * @phpstan-param \Closure() : T $closure
+	 * @phpstan-return T
+	 */
+	final protected function callDepth(\Closure $closure) : mixed{
 		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)");
@@ -55,13 +70,9 @@ public function call() : void{
 		$timings = Timings::getEventTimings($this);
 		$timings->startTiming();
 
-		$handlers = HandlerListManager::global()->getHandlersFor(static::class);
-
 		++self::$eventCallDepth;
 		try{
-			foreach($handlers as $registration){
-				$registration->callEvent($this);
-			}
+			return $closure();
 		}finally{
 			--self::$eventCallDepth;
 			$timings->stopTiming();

src/event/HandlerList.php

@@ -24,9 +24,11 @@
 namespace pocketmine\event;
 
 use pocketmine\plugin\Plugin;
+use function array_filter;
 use function array_merge;
 use function krsort;
 use function spl_object_id;
+use function usort;
 use const SORT_NUMERIC;
 
 class HandlerList{
@@ -128,11 +130,26 @@ public function getListenerList() : array{
 		}
 
 		$listenersByPriority = [];
+		$asyncListenersByPriority = [];
 		foreach($handlerLists as $currentList){
 			foreach($currentList->handlerSlots as $priority => $listeners){
-				$listenersByPriority[$priority] = array_merge($listenersByPriority[$priority] ?? [], $listeners);
+				$syncListeners = array_filter($listeners, static function(RegisteredListener $listener) : bool{ return !($listener instanceof RegisteredAsyncListener); });
+				$listenersByPriority[$priority] = array_merge($listenersByPriority[$priority] ?? [], $syncListeners);
+
+				$asyncListeners = array_filter($listeners, static function(RegisteredListener $listener) : bool{ return $listener instanceof RegisteredAsyncListener; });
+				$asyncListenersByPriority[$priority] = array_merge($asyncListenersByPriority[$priority] ?? [], $asyncListeners);
 			}
 		}
+		foreach($asyncListenersByPriority as $priority => $asyncListeners){
+			usort($asyncListeners, static function(RegisteredAsyncListener $a, RegisteredAsyncListener $b) : int{
+				if($a->canBeCallConcurrently()){
+					return $b->canBeCallConcurrently() ? 0 : -1;
+				}else{
+					return $b->canBeCallConcurrently() ? -1 : 0;
+				}
+			});
+			$listenersByPriority[$priority] = array_merge($listenersByPriority[$priority] ?? [], $asyncListeners);
+		}
 
 		//TODO: why on earth do the priorities have higher values for lower priority?
 		krsort($listenersByPriority, SORT_NUMERIC);

src/event/ListenerMethodTags.php

@@ -31,4 +31,5 @@ final class ListenerMethodTags{
 	public const HANDLE_CANCELLED = "handleCancelled";
 	public const NOT_HANDLER = "notHandler";
 	public const PRIORITY = "priority";
+	public const NO_CONCURRENT_CALL = "noConcurrentCall";
 }

src/event/RegisteredAsyncListener.php

@@ -0,0 +1,65 @@
+<?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\plugin\Plugin;
+use pocketmine\promise\Promise;
+use pocketmine\timings\TimingsHandler;
+
+class RegisteredAsyncListener extends RegisteredListener{
+	/** @phpstan-var Promise<null> $returnPromise */
+	private Promise $returnPromise;
+
+	/**
+	 * @phpstan-param \Closure(AsyncEvent&Event) : Promise<null> $handler
+	 */
+	public function __construct(
+		\Closure $handler,
+		int $priority,
+		Plugin $plugin,
+		bool $handleCancelled,
+		private bool $noConcurrentCall,
+		TimingsHandler $timings
+	){
+		$handler = function(AsyncEvent&Event $event) use($handler) : void{
+			$this->returnPromise = $handler($event);
+			if(!$this->returnPromise instanceof Promise){
+				throw new \TypeError("Async event handler must return a Promise");
+			}
+		};
+		parent::__construct($handler, $priority, $plugin, $handleCancelled, $timings);
+	}
+
+	public function canBeCallConcurrently() : bool{
+		return !$this->noConcurrentCall;
+	}
+
+	/**
+	 * @phpstan-return Promise<null>
+	 */
+	public function callAsync(AsyncEvent&Event $event) : Promise{
+		$this->callEvent($event);
+		return $this->returnPromise;
+	}
+}

src/player/Player.php

@@ -1517,6 +1517,7 @@ public function chat(string $message) : bool{
 					if(!$ev->isCancelled()){
 						$this->server->broadcastMessage($ev->getFormatter()->format($ev->getPlayer()->getDisplayName(), $ev->getMessage()), $ev->getRecipients());
 					}
+
 				}
 			}
 		}