API Change Proposal: Events Loop 2.0

[Osspial]

UPDATE 8/23/18:

A PR for Windows is available at #638

UPDATE 7/12/18:

I've adapted the agreed-upon changes into a changelog here: https://gist.github.com/Osspial/d3a3390807fa95a469d9c9b677db4715. The original proposal is below.

---

Events Loop 2.0

This issue proposes a series of changes to winit's EventsLoop API, based around the experiences I've had with creating a GUI library that uses winit as a window creation backend. The main goal is to give winit complete control over the event loop, both for event polling and event waiting. These changes should let us fix various implementation bugs on the win32 backend, as well as fix what I believe are design bugs in the current API.

Technical Motivation:

EDIT: The technical motivation for the Windows backend is included below. However, pretty much every platform winit supports is hacky or broken in some way by necessity of the current API we expose.

Right now, the win32 backend creates a background thread, in which the events loop resides. The biggest problem with this is that it introduces various unexpected synchronization bugs that require a good amount of effort to fix and increase the complexity of the backend (see #415 and #391). However, it's necessary to cleanly handle win32's various modal event loops.

So, what are these modal loops, and why do they matter? On Windows, when a user begins resizing a window, Windows suspends the program's main event loop and begins its own loop, inside of the resize event's handler. Unfortunately, this freezes any processing that's going on outside the Windows event loop, which is currently worked around by having the loop exist in its own thread, introducing quite a few bugs as mentioned above. Inside the loop, Windows does a bunch of additional processing, most notably handling window snapping (although it probably does other stuff too that isn't obvious).

Windows doesn't publicly expose the APIs used to handle snapping, so re-implementing the modal loops ourselves so that they don't suspend the main event loop isn't really an option. However, Windows should still process events we push to the Windows events queue, letting us implement event polling inside the Windows event loop with custom events (using the same mechanisms used for wakeup messages), as long as winit's API lets it assume complete control over program control flow. Right now, it doesn't, but this change would let us remove the second thread and simplify much of the implementation.

Actually removing the second thread isn't that difficult (see #445), but these bugs present pretty major blockers that should be resolved before that's merged.

Design Details

EDIT: The original design has been removed from this post, as it is outdated and may cause confusion for new readers. However, it does contain some useful information about the rationale behind the changes, and can be accessed here: https://gist.github.com/Osspial/53efa87797899872650f6bece14736c0

[elinorbgr]

I don't have much to say about the API itself (I'm not that much used to writing apps with winit tbh), just commenting to say I don't see any strong incompatibility / difficulty with implementing this regarding to the wayland backend.

The most tricky part will be handling WaitWithTimeout, which will require to do some manual epoll, that's all I see.

[francesca64]

I think it's too opaque to have Refresh mean both "event processing finished" and "OS requested redraw", and if we were to go through with this, the name Refresh should probably be changed altogether. I can see some users thinking it represents vertical refresh, and it's just not very descriptive in general.

My grasp of your intended ControlFlow enum is a little unclear. Do you want users to be able to switch between these strategies at will during the event loop? Is that something we can implement effectively?

I'm curious how you'd say this proposal is better than #231, as your Refresh machinery seems to exist to solve the same problem (and get_event seems cleaner to me). I definitely agree that the current API has problems, and I'm starting to get the impression that the current model is incompatible with most platforms. At this point, I'm wondering if we should just invert the control flow, since unless I'm missing something, it seems like the most straightforward solution.

Additionally, since this is an area that has such an immediate and substantial impact on users, before acting on anything I'd want to see a lot of feedback. When we've achieved a good enough internal consensus, I think it would be a good idea to discuss it in other places in the community, and we'd hopefully be able to deliver an API change that people are hyped for, rather than one that unceremoniously breaks their application one morning.

[willglynn]

I think a breaking API change is necessary, but it must require the user to entirely surrender their thread. A callback-only API would fix Windows, it would fix MacOS (which has nearly identical resizing gotchas described in #219), it would fix the web (which needs to return to the browser to deliver more events), it would fix iOS and Android (which likewise expect to run the event loop), etc.

Going callback-only is a massive breaking change, but it's the right move. Most platforms expect to call user code from the UI thread when things happen, while winit tells its users that they can keep the UI thread and occasionally call into the platform. That is why this is hard.

Dropping run_forever() in favor of a new API that takes over your thread would be a massive breaking change, but it is possible to glue both models back together again using the pattern from #237. We could make a winit-compat crate that provides run_forever() on top of a new callback-only API via coroutines, and it could work on the major platforms.

Having said all that, while I am convinced that this is the right way forward, I am not in a position to be the champion of this approach. I no longer use winit and can't justify investing the required time and effort into making this happen.

[francesca64]

@willglynn I'd say I'm in a good position to be the champion of this approach. If necessary, I'd even implement it for every platform, though for my sake it hopefully wouldn't come to that.

At this point, I'm quite convinced that this is of great importance. Interfacing with platform APIs the correct way is already hard enough, and our current approach doesn't seem to be doing any favors for the users, contributors, or maintainers.

I'm not sure how necessary the winit-compat idea is. Good migration documentation and coordinating with projects could go a long way.

Anyway, now we just need to get the approval of... basically everyone.

[elinorbgr]

I would be in principle in favor of such a change on the winit API (going callback-only), though I'm not sure how much my opinion count on that, the fact remaining that wayland as a platform remains pretty accommodating regarding control-flow handling.

Though, if such a thing starts going, I'd like to emphasize the need for good planning ahead (maybe going through an RFC-like process ?), in order to clearly define the contents and guarantees of the API, in order to allow easier coherence in backend implementations.

Typical questions that in my opinion need to be clearly addressed are for example:

• guarantees and requirements regarding thread-safety (what is Send and/or Sync ?)
• if winit takes control of the thread, do we insert a mechanism allowing users to insert other kind of sources of events in the event loop?

[kvark]

@francesca64

I'd say I'm in a good position to be the champion of this approach. If necessary, I'd even implement it for every platform, though for my sake it hopefully wouldn't come to that.

viva de revolution! I'd be happy to provide limited assistance (got all platforms by hand).

Anyway, now we just need to get the approval of... basically everyone.

You have my seal of approval. Can also speak about some of the clients of winit:

• gfx-rs/examples and vange-rs: need a way to schedule a frame (at a timeout, or just on idle), no other issues are expected
• gfx-hal/examples: will benefit from NSAutoreleasePool being automatic on OSX/Metal
• three-rs: will need to own the main loop in order to give that ownership to winit (similarly, any middleware using winit would have to own the main loop after the change), also needs to schedule a frame, otherwise should be good
• webrender/wrench: already using run_forever

[Osspial]

@vberger My instinct is to make Windows Send and Sync, and then have the EventsLoop structure itself be locked to a single thread. I know this would work on Windows, as it's essentially what's already there, but I don't know how it would work on other platforms.

@francesca64 I can see your point with having Refresh mark the end of event processing, but I'm not sure if I agree with it. An alternative would be to have queue_refresh immediately send a Refresh event to the user, but I don't see a situation arising where someone would want to redraw immediately inside of the event loop. Regardless, there probably should be an event that communicates when the event loop is going to resume waiting - WaitBegin, perhaps? Also, even if this isn't the API we settle on, I do feel like we should rename Refresh to Redraw, as that communicates its purpose better.

My goal with the ControlFlow enum is to have it tell winit when it should call back into user code, and to allow the application to cleanly switch between updating constantly, updating intermittently and being suspended. This should be possible on Windows by switching between calling GetMessage and PeekMessage, and I'm assuming there's equivalent code to do this on other platforms, but I couldn't say with any certainty.

@willglynn basically explained the advantages of this API over the get_event API - while get_event is cleaner, and I'd rather use it if the underlying platforms allowed for it, the majority of platforms assume the OS is driving the event loop. A callback-based API fits into the OS event loop way better than the iterative design you get with get_event.

[Osspial]

I'd be able to implement this on Windows, at least, as it should be a fairly simple change to my current single-threaded win32 branch.

[willglynn]

A common pattern that pops up in this space is sending yourself a message, particularly to communicate things from other threads onto a UI thread. This can usually be expressed directly using platform-specific hooks, and when it can't, it can be synthesized.

This pattern often separates concerns: you end up writing event handling code to handle the message you sent from some other context and do whatever it asks you to do.

An alternative to consider:

fn run_in_event_loop<F>(f: F) where F: FnOnce(), F: Send + 'static

Instead of sending custom events to the event loop, send closures to run within the event loop. (Platforms could implement this by sending themselves a message – though there are a few alternatives on Mac/iOS and a native closure queueing mechanism on the web.) This ability to easily execute code within the event loop from arbitrary contexts could substantially reduce the need for other thread-safe interfaces.

[Osspial]

@willglynn An issue I can see with that is that any closures you pass through that function don't gain access to the data in the main UI closure, which would limit pretty heavily what you could do with the passed closure. Passing custom events which are handled by the main event closure gives you access to that data. How would that be handled? The best solution I can see would be to wrap all the data in the main UI closure in a Rc<RefCell<...>>, but that doesn't seem ideal.