From 412516159f3d93c666f366e0067c1aaab6bde0b3 Mon Sep 17 00:00:00 2001 From: Osspial Date: Thu, 13 Jun 2019 12:51:44 -0400 Subject: [PATCH] Document the caveats of run_return (#914) --- src/platform/desktop.rs | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/platform/desktop.rs b/src/platform/desktop.rs index 05783890..1fafb0dd 100644 --- a/src/platform/desktop.rs +++ b/src/platform/desktop.rs @@ -16,6 +16,16 @@ pub trait EventLoopExtDesktop { /// /// Unlike `run`, this function accepts non-`'static` (i.e. non-`move`) closures and returns /// control flow to the caller when `control_flow` is set to `ControlFlow::Exit`. + /// + /// # Caveats + /// Despite its apperance at first glance, this is *not* a perfect replacement for + /// `poll_events`. For example, this function will not return on Windows or macOS while a + /// window is getting resized, resulting in all application logic outside of the + /// `event_handler` closure not running until the resize operation ends. Other OS operations + /// may also result in such freezes. This behavior is caused by fundamental limitations in the + /// underyling OS APIs, which cannot be hidden by Winit without severe stability reprecussions. + /// + /// You are strongly encouraged to use `run`, unless the use of this is absolutely necessary. fn run_return(&mut self, event_handler: F) where F: FnMut(Event, &EventLoopWindowTarget, &mut ControlFlow); }