Generalize asynchronous events

[ShockedPlot7560]

Introduction

This PR would be more of a foretaste for #6015 in that it provides a means of generalizing asynchronous event calling.

An asynchronous event in this context is one whose action can be deferred by plugins specifying promises to be resolved.
The integrity of event priorities is guaranteed by calling them one by one. Before moving on to the next priority, we wait until all the promises of the current one have been fulfilled.
Only the state of the server and player context can't be guaranteed. However, the state of the event is unaffected, whether it is called asynchronous or synchronous.

Behaviour

When a listener of an asynchronous event returns a Promise, the event is marked as asynchronous and placed at the end of the call stack for its priority.
When a callAsync is called, the call flow is as follows:

1. for each priority:
   2. call async handlers which allows concurrent execution
   3. for each async handlers which doesn't allows concurrent execution:
       1. wait for previous promises
       2. clear all the promise
       3. call the handler and add the return promise into the waiting list
   4. wait for all promises
2. the promise returned by callAsync is resolved with their instance

In this way, each listener can add only one promise.
If, on the other hand, the handler is sensitive to changes in the event, it is preferable to add the @exclusiveCall tag, which specifies that it must be the only one being called.

Event transformation

If we wanted to implement the asynchronous chat event, this would look like this:

class PlayerChatAsyncEvent extends AsyncEvent implements Cancellable{
	use CancellableTrait;
... Logic here
}

When calling:

$ev = new PlayerChatAsyncEvent($this, $messagePart, $this->server->getBroadcastChannelSubscribers(Server::BROADCAST_CHANNEL_USERS), new StandardChatFormatter());
$ev->callAsync()->onCompletion(function(PlayerChatAsyncEvent $ev) : void{
	if(!$ev->isCancelled()){
		$this->server->broadcastMessage($ev->getFormatter()->format($ev->getPlayer()->getDisplayName(), $ev->getMessage()), $ev->getRecipients());
	}
}, function() {
	// NOOP
});

Changes

API changes

• Add AsyncEvent class
• Add Promise::all()

Behavioural changes

Backwards compatibility

Not for the moment

Follow-up

n/a

Tests

class Main extends PluginBase implements Listener{
	protected function onEnable() : void{
		$this->getServer()->getPluginManager()->registerEvents($this, $this);
	}

	public function onPlayerChatAsyncConc1(PlayerChatEvent $event) : Promise {
		return $this->timeout("Player " . $event->getPlayer()->getName() . " chat async concurrent 1");
	}

	public function onPlayerChatAsyncConc2(PlayerChatEvent $event) : Promise {
		return $this->timeout("Player " . $event->getPlayer()->getName() . " chat async concurrent 2");
	}

	/**
	 * @exclusiveCall
	 */
	public function onPlayerChatAsyncNoConc(PlayerChatEvent $event) : Promise {
		return $this->timeout("Player " . $event->getPlayer()->getName() . " chat async exclusiveCall");
	}

	private function timeout(string $message) : Promise {
		$promise = new PromiseResolver();

		$this->getScheduler()->scheduleDelayedTask(new ClosureTask(function() use ($message, $promise) {
			$this->getLogger()->debug("Resolving promise for message " . $message);
			$promise->resolve(null);
		}), 5 * 20);

		return $promise->getPromise();
	}
}

[ShockedPlot7560]

New behaviour

Above all, the logic of synchronous events remains the same, even for asynchronous events, as long as they are called synchronously.

When a listener of an asynchronous event returns a Promise, the event is marked as asynchronous and placed at the end of the call stack for its priority.
When a callAsync is called, the call flow is as follows:

1. for each priority:
   1. call sync handlers (return type is different than Promise).
   2. call async handlers which allows concurrent execution
   3. for each async handlers which doesn't allows concurrent execution:
       1. wait for previous promises
       2. clear all the promise
       3. call the handler and add the return promise into the waiting list
   4. wait for all promises
2. the promise returned by callAsync is resolved

In this way, each listener can add only one promise.
If, on the other hand, the handler is sensitive to changes in the event, it is preferable to add the @noConcurrentCall tag, which specifies that it must be the only one being called.

[SOF3]

tldr AsyncEventDelegate, will look again when PR is ready

No longer valid

[ShockedPlot7560]

As I understand, now, we will accept async listeners to return null or Promise ?

[dktapps]

As I understand, now, we will accept async listeners to return null or Promise ?

Yep, they'll allow the next handler in the queue to be called immediately if returning null

[dktapps]

I think the main thing still on the TODO list is to buffer incomplete events. The existing mechanism using stack depth won't cut it. We need a way to track which handlers didn't fulfil their promises so that the correct plugin can be properly blamed when an event fails to complete.