winit: Winit `run_return` and Android does not get `Resumed` and `Suspended`

I don’t think I’m going to have time to do this tonight, and will be away/busy until wednesday now but can hopefully follow up on this later in the week.

Yeah, no rush with it.

After syncing internally two things are clear about the needs from our engine

1. Our current logic relies on an exit code to report errors, flush queued up logs and other things may not have fully completed. Comment: This can be reworked to worked to be included into a event loop and nothing appears to be preventing this. Just needs a bit of work.

2. We need tight control over frame phasing, at least on traditional desktop platforms. Mobile is a bit unclear how much we need/can control frame phasing at the moment but might change in the future. Comment: I cannot emphasize enough how important the rendering timing for a game engine, maybe this is already accounted for on relevant platforms? Another long term thing we consider is having some support for technologies like Nvidia Reflex

Summary

From the information I have gathered it appears that nothing is blocking us from ultimately switching to a pure run implementation. Given that requirement 2 is either already possible or can be fleshed out in the future. Though short term its probably not the solution to switch directly, but rather investigate and poke at the problem internally. Short to mid term, it would beneficial to have run that can return with an exit code and not be called again. Especially considering the requirement mentioned here #2709. Where on iOS and Web, that does not return, special treatment will have to done on these platforms on the application layer if the application assumes a return is expected.

okey, I’d like to clarify a couple of things in the discussion with @kchibisov and then take a step back considering @Hoodad’s follow up…

1st, another ambiguity with what “polling” means…

How would you do polling on macOS though or on Windows? They would be able to poll events into Vec ondemand, likely like they do right now, they won’t be able to put winit inside e.g. epoll to get notified.

What I want for X11/Wayland is an ability to put winit inside the calloop(maybe mio) as an event source, because it has FD and such exposed. I doubt you can do something like that on macOS, but what you can do is to run_return, push to Vec and then process outside the run_return (it’s also polling, but active one).

@kchibisov I think we still have some semantic ambiguity around what “polling” means (separate from the ondemand confusion we had) which is still making it tricky to be clear in this discussion…

At the moment when you’re talking about “polling” you’re focused on the lower-level OS polling, e.g. as done in mio, such as epoll on Linux, and that’s is relevant to this discussion but we also need a way to be clear when we’re talking about the higher level polling that was illustrated in the example for this issue, using run_return.

I’m going to borrow the term event “pumping” from SDL here because it seems like a good parallel that gives us a separate word from “polling”.

So in this context (based on the example linked for this issue) we can say that (for some platforms) it’s possible to try and integrate Winit into an external even loop by calling run_return as a way to “pump” the events for each iteration of the external event loop. In this variation of polling then the app or engine still receives its events via the regular event loop closure/callback and if the app wants to move any event handling outside of winit, into their own event loop, then it’s actually their responsibility to buffer those events however they want, to be processed after run_return exits (such as with the Resumed event in the example).

So for this “event pumping” use case, the OS doesn’t necessarily need to support a direct equivalent to epoll (not possible with RunLoops on MacOS) so long as there is some way to trigger a flush, read, check and process sequence to handle any pending events (basically run the event loop for a very short amount of time).

So to answer your question about “How would you do polling on macOS though or on Windows” we need to clarify that we were talking about different kinds of polling and my proposal was really to enable “event pumping” as above (as done in the example for this issue)

To align terms here, lets tweak the API from my proposal to .start(), .event_pump() and .finish().

Event pumping effectively just requires that it’s possible to call (something like) run_return() to process a single iteration of the event loop with a timeout so that it doesn’t block indefinitely if there are no pending events. The main desktop OS where that’s fiddly is MacOS but it is possible to start a RunLoop with a timeout, so it would run the loop just long enough to dispatch pending events. This is what SDL does: https://github.com/rust-windowing/winit/issues/2706#issuecomment-1464051125 and would be a pretty small change (I’d guess) to the existing macos backend.

Break down of use cases + terms that are intertwined with this issue / discussion

1. We have typical apps that just run the event loop continuously, handling all events inside the event loop closure, and app will exit when the event loop exits (no polling of any kind, and the recommended, portable way to run most Winit apps)
2. The #2431 “ondemand” use case where an app wants to be able to call something like run_return to run the event loop temporarily and handle events normally (inside the Winit closure). After the event loop exits it’s possible the app may want to re-run the event loop for a new, temporary UI.
3. The “event pumping” use case of this issue. The app wants to integrate Winit with an external event loop by calling into an API similar to run_return (or .event_pump()) once per iteration of their external loop. This will run the event loop for a very short period of time to flush and handle events (via the event loop closure). It’s assumed that the app or engine may try to buffer events and move the real handling outside of the Winit closure into their external loop instead (unsynchronized event processing). (It’s that last step that causes the majority of the portability hazards here)
4. The Smithy use case (some guesswork here based on your latest comments @kchibisov) where an application wants to integrate Winit into an external event loop based on file descriptor polling. In this case I expect the requirement is that you can get a file descriptor for a Winit event loop that can e.g. be given to mio or similar so an external component will handle polling for events. When events are available then a function similar to run_return (such as .event_pump()) can be called that will handle all events normally (inside the Winit closure). I guess for this use case that events are handled, properly synchronized, inside Winit, not unsynchronized, like with (3)/event pumping.

I think that my proposal to add .start(), .event_pump() and .finish() APIs would be applicable for (3) and (4) but I was only thinking about (3) initially. The Smithy use case (4) would also need a way to pump events when the external polling sees that there are events are available.

@kchibisov It would be good if you can clarify whether the Smithy use case deals with all event handling synchronized, inside the Winit event loop closure, to see if (3) is the only use case that is trying to handle events unsynchronized, outside of the Winit event loop.

What to do?

Based on being able to handle each of the above use cases, I do generally still think my proposal at the end of https://github.com/rust-windowing/winit/issues/2706#issuecomment-1462423107 was viable - and potentially not that complex to implement either. (and it also sounds OK to not fully consolidating run across iOS / web, as discussed).

That said though, the use case (3) for this issue depends on unsynchonized handling of events which is not a recommendable, portable design in general.

I think it would technically be relatively simple to support the use case for this issue across Windows, Linux, MacOS and Android with the various caveats and portability hazards discussed earlier - but I tend to think this usage model should only be endorsed if:

1. It’s genuinely being helpful / pragmatic for an existing, real-world use case
2. It’s genuinely difficult in the short term for the existing engine that @Hoodad is working with to be able to synchronize its event handling inside the Winit event loop closure.

One thing to consider is that it may be feasible to incrementally move handling inside Winit until getting to a point where you could hopefully then switch over to just using run instead of event pumping.

In terms of:

In the end I think what should be the driving factor for a change is the drive to make winit as cross-platform as possible. Which may end up with winit not being the most perfect choice for our particular use-case. Or it may just be that things workout just fine.

I would certainly say that the use case (3) illustrated by the example for this issue is not a recommendable portable design if it can be avoided (at the very least it would be impossible to support on Web and iOS and has a list of hazards on other OSs too)

But still, it would be possible (and potentially not difficult) to enable some pragmatic support for it (and the same solution looks like it would also be applicable to the Smithy use case (4))

Having read through all the posts, thoughts and suggestions I now start to get a clearer picture of the why certain things are the way the are. When I started this thread I, in my admittingly naïve world view, assumed that polling was the way you would preferably handle events, like as mentioned GetMessage and PollNextEvent. I can see that most of my experiences using polling API’s may just be coming from polling events from an input device. And learning more about how different platforms like iOS and Android handles the system events I can understand the reasoning better why they do what they do. I also get a sense of there being a bit of a shift towards doing more event based loops in the more modern takes on window API’s, but that may just boil down to the newer API’s being more focused on mobile and energy efficiency by giving more control to the OS over the applications lifetime and resources.

With this being said, I’m open to adjust my previous stated stance about trying to stick to run_return. However, reading through what’s been said it feels like run isn’t ideal for Android, Windows and in general platforms that can return an exit code. In my particular case the current biggest unknown feels like if there is code that needs to run after the event loop has finished. I will investigate next week.

In the end I think what should be the driving factor for a change is the drive to make winit as cross-platform as possible. Which may end up with winit not being the most perfect choice for our particular use-case. Or it may just be that things workout just fine.

Not familiar with the history of run_return, I’d be fine with deprecating it in 0.28 and removing it in 0.29 (unless we get reports that we shouldn’t).

Linking the lightning talk that @Osspial did three years ago about this problem. I think the issue with not having ! as the return type is that users kind of expect that they can do stuff after run, which they can’t.