Remove RedrawEventsCleared + MainEventsCleared, and add AboutToWait

[rib]

This is one of the follow ups for #2900, assuming that #2767 hopefully lands soon.

The idea that redraw events are dispatched with a specific ordering that makes it possible to specifically report when we have finished dispatching redraw events isn't portable and the way in which we dispatched RedrawEventsCleared was inconsistent across backends.

More generally speaking, there is no inherent relationship between redrawing and event loop iterations. An event loop may wake up at any frequency depending on what sources of input events are being listened to but redrawing is generally throttled and in some way synchronized with the display frequency.

Similarly there's no inherent relationship between a single event loop iteration and the dispatching of any specific kind of "main" event.

An event loop wakes up when there are events to read (e.g. input events or responses from a display server / compositor) and goes back to waiting when there's nothing else to read.

There isn't really a special kind of "main" event that is dispatched in order with respect to other events.

For what MainEventsCleared is used for by applications then the most portable interpretation of what applications want is to know when the event loop is about to block and wait for new events.

In practice most applications almost certainly shouldn't care about this because the frequency of event loop iterations is essentially arbitrary but it's reasonably portable to expose this.

MainEventsCleared has been renamed to AboutToWait and is the last event emitted in each iteration of the event loop.

• Tested on all platforms changed
• Added an entry to CHANGELOG.md if knowledge of this change could be valuable to users
• Updated documentation to reflect any user-facing changes, including notes of platform-specific behavior

Note: the base for this PR isn't currently set to master, since it's stacked on the changes for #2975

[kchibisov]

The change is implemented correctly internally, however the top level docs are wrong, given that you've basically renamed RedrawEventsCleared, but made it in a way that it'll make sense.

And MainEventsCleared is the thing you've actually removed, not RedrawEventsCleared.

The top level docs are all wrong in the end. Basically we should say that the event is emitted when the event loop is about to go to sleep. We could also comment that you could request_redraw from it to wake up a loop once OS will think that it's a good time to draw.

@daxpedda I remember that on Web and likely on macOS due to its callback design the time between so called poll intervals could be really long. So the users should rely on redraw_requested for contiguous drawing based on the request animation frame (and on macOS based on some display link calls).

@rib that means that we should probably just say that the AboutToWait is called when the event is about to go back to waiting for events, meaning that we should drop all the mentions in relative to rendering.

We could also say that no event could occur after this event (right?).

[rib]

And MainEventsCleared is the thing you've actually removed, not RedrawEventsCleared

This is semantics.

I actually did a sed to initially rename MainEventsCleared (the command in my bash history was find ./ -iname '*.rs' -exec sed -i 's/MainEventsCleared/AboutToWait/g' {} \;) and then while going through and manually removing RedrawEventsCleared I made sure AboutToWait was the last event emitted.

The exact provenance isn't super important but at least the way that I intuitively see it is that I removed RedrawEventsCleared and renamed MainEventsCleared since that's actually what I did from a typing pov.

all that really matters here is the end result.

[kchibisov]

This is semantics.

This is true, but the documentation is now wrong.

[rib]

Okey, I've tried to do a better job of updating the docs - sorry I didn't really do that properly before.

[rib]

This is semantics.

This is true, but the documentation is now wrong.

With the updates I've just pushed I've generally reframed it as having removed both events and added a new AboutToWait event.

This only really affects the commit message and the changelog though.

[rib]

Although I put a small note about Web in the commit message, I wonder if we should have a small platform-specific note for AboutToWait that highlights that this is emulated on Web (similar to how MainEventsCleared was dispatched) since the real event loop is an implementation detail of the browser that we can't observe.

[kchibisov]

We'll have to target a different branch now though.

[rib]

We'll have to target a different branch now though.

github will automatically move the base branch along if they are merged in the order they are stacked