EventLoop 3.0 Changes

[rib]

Considering the changes being made for run()-> Result<>, pump_events, run_ondemand, and addressing inconsistent ordering guarantees for events like MainEventsCleared and RedrawRequested, as well as removing and renaming several core events, then it feels like a similar level of change as happened for EventLoop 2.0.

The details are a bit scattered though, and although some things have been agreed as part of lengthy issue discussions we still need to track those ideas at least as a reminder as to what is left to do.

I'm going to be lite on details here, but a lot of the background discussion probably happened here #2706 and maybe a few other issues we can link back here too.

• Replace run() ->! with run() -> Result as our portable run API available on all platforms (Re-work event loop run APIs: adds run -> Result<>, run_ondemand and pump_events #2767)
• Replace run_return() with pump_events() and run_ondemand() (for Windows, macOS, Linux + Android) (Re-work event loop run APIs: adds run -> Result<>, run_ondemand and pump_events #2767)
• Maybe add run_noreturn() ->! extension API for iOS (discussed in Return immediately from run_app on web #4165)
• Rename LoopDestroyed LoopExiting (Rename LoopDestroyed to LoopExiting #2975)
• Remove RedrawEventsCleared (Remove RedrawEventsCleared + MainEventsCleared, and add AboutToWait #2976)
• Rename MainEventsCleared -> AboutToPoll AboutToWait (Conceptually NewEvents and AboutToWait can be seen as a way to observe the underlying blocking/polling of the event loop - similar to registering an observer with a macOS RunLoop) (Remove RedrawEventsCleared + MainEventsCleared, and add AboutToWait #2976)
• Document that RedrawRequested is no longer guaranteed to be delivered in order with respect to any other event - it is platform specific
• Make it clearer that applications should redraw any time they get a RedrawRequested callback (and they shouldn't defer the redraw outside of the winit callback).
• Make it clearer that Resumed events are delivered on all platforms (not just mobile) and Resumed events are a good place to initialize an application because it's the first point where it's possible to start creating Windows across all platforms.
• Remove lifetime from the Event
• Aim to implement RedrawRequested throttling by default where there's a suitable mechanism provided by the window system
  • By WM_PAINT on Windows
  • Either with drawRect or display link on macOS (same for iOS?) (Implement VSync source (frame pacing) #2412)
  • By frame callbacks on Wayland
  • Via requestAnimationFrame for Web
  • Maybe via Choreographer on Android
  • By praying on X11

I don't mind if we want to collate this information somewhere else, or in a different, better way etc but wanted to a least get a basic task list laid out somewhere

Maybe a milestone would be a nicer way to organize this?

[rib]

CC: @kchibisov, @msiglreith, @madsmtm, @daxpedda

[notgull]

• Maybe add run_noreturn() ->! extension API for iOS and Web

+1 to this. Maybe it could also be implemented for all of the non-Android platforms, which use std::process::exit() instead.

• Make it clearer that Resumed events are delivered on all platforms (not just mobile) and Resumed events are a good place to initialize an application because it's the first point where it's possible to start creating Windows across all platforms.

Maybe we build this into the type system? I.e. Resumed returns a WindowCreationToken or something that can't be created outside of winit, that is needed to create windows?

The only other thing is that RedrawEventsCleared was nice for submitting the wgpu queue for when all redraws are done. It would be nice if something similar were exposed on platforms that support it.

Looks good to me, otherwise! Can't wait.

[kchibisov]

+1 to this. Maybe it could also be implemented for all of the non-Android platforms, which use std::process::exit() instead.

This API only required on ios.

The only other thing is that RedrawEventsCleared was nice for submitting the wgpu queue for when all redraws are done. It would be nice if something similar were exposed on platforms that support it.

It'll be named AboutToPoll.

[kchibisov]

Wrt MainEventsCleared and RedrawEventsCleared, I think MainEventsCleared is here to stay with us. The reason for that is that winit has a guarantee right now is that if you do request_redraw prior to MainEventsCleared including it, it'll be scheduled on this loop iteration.

While throttling adds a bit to that, I think it'll still be nice to have such entry point to potentially schedule the redraw on this loop iteration, so for example when after processing input events, you decided to request a redraw, so if on e.g. Wayland you already had frame callback, you could simply draw on this loop iteration reducing the overall latency.

[kchibisov]

Wrt to window creation, we know that it's generally async, maybe we should expose it? Though, I'm thinking that it'll too much. But that, however will make it work with Resumed without a type system level token and such, you could request a window outside of the loop, but you'll get it only once you start the loop.

It could be like Window::request_new() -> Result<WindowId, Err>, so you're getting a WindowId ahead of time for your new window, thus you could have a spot for it in the HashMap for example. And then you receive an even with the Window, that way you won't have issues with calling inner_size way too early, because the window will be still in process, and you won't have an issue with callback stacking if we decide to call from e.g. wayland events being dispatched directly to the user.

But I fill like that could be a bit a change in convenience, but generally speaking it'll improve situation wrt correctness, given that you really want to create EGLSurface for Wayland with the right size from the start, and not with some arbitrary size you pick, it's possible right now, but users rely on their sizes and not on inner_size() calls, and on some systems inner_size() is not ready early on.

Besides, macOS has issues in general when it comes to creating windows out side of the loop, so some windowing features stop working (alacritty thus moved to Resumed event instead).

[rib]

Wrt to window creation, we know that it's generally async, maybe we should expose it?

I think it could be good to expose that window creation is async and fix the awkward issue with Wayland right now with the sync roundtrip in Window::new() - that is having a really disproportionate affect on the whole design of the Wayland backend currently.

I don't know about really buffering requests to create a window right from before an event loop is started. It's always seemed a bit odd to me with Winit that you could create windows before starting to run an EventLoop.

The idea of initially just getting a WindowId sounds like it could work.

In terms of sizes to use with EGL there's another big mess imho with the inner_size API being overloaded which is a separate issue really.

It wouldn't necessarily always bad for apps to optimistically use a size that was used to request a new window for an egl surface if it e.g. means they don't have to wait for a round trip - if it's 99% likely they get what they asked for and the other 1% will correct itself via resize events etc.

[rib]

The only other thing is that RedrawEventsCleared was nice for submitting the wgpu queue for when all redraws are done

There would no longer be any notion of having multiple redraw events within a single iteration of the loop - you just get (throttled) RedrawRequested events in response to calling request_redraw() - so now you would just submit work to the GPU as part of your RedrawRequested event handler (i.e. after you've finished actually drawing). If we kept a RedrawEventsCleared then conceptually it would just be called back-to-back, immediately after the RedrawRequested event - which makes it pretty much redundant.

[daxpedda]

I don't think we want a run_noreturn() -> ! as an extension API for Web if we already have spawn.
Is this desirable somehow?

[kchibisov]

I also don't quite understand why we have an api which -> ! if web doesn't really need it.

The whole point was to move away of -> !, which is basically ios, and ios in my opinion could live in its own with -> !, given how niche the platform is for rust development, and that users targeting it likely have a separate path regardless.

The only issue is that I think spawn on web doesn't block at all? While the default API we want should block the caller until run finishes.

[daxpedda]

The only issue is that I think spawn on web doesn't block at all? While the default API we want should block the caller until run finishes.

Yes, that unfortunately can't be fixed in Web.

[kchibisov]

I think we've discussed in the past and we could have a way to block via the exception handler, basically the way run -> ! was implemented before.

[daxpedda]

I think we've discussed in the past and we could have a way to block via the exception handler, basically the way run -> ! was implemented before.

Whats the "exception handler"? Right now run -> ! on Web is implemented by throwing a panic, which "works".

[rib]

I think we've discussed in the past and we could have a way to block via the exception handler, basically the way run -> ! was implemented before.

Whats the "exception handler"? Right now run -> ! on Web is implemented by throwing a panic, which "works".

oh, sorry, I didn't mean 'exception handler' I meant the trick with throwing - just wasn't thinking when typing ;-p