Return immediately from run_app on web

This avoids using JavaScript exceptions to support `EventLoop::run_app`
on the web, which is a huge hack, and doesn't work with the Exception
Handling Proposal for WebAssembly:
https://github.com/WebAssembly/exception-handling

This needs the application handler passed to `run_app` to be `'static`,
but that works better on iOS too anyhow (since you can't accidentally
forget to pass in state that then wouldn't be dropped when terminating).

Author: madsmtm

src/application.rs

@@ -11,8 +11,7 @@ use crate::window::WindowId;
 /// See [the top-level docs] for example usage, and [`EventLoop::run_app`] for an overview of when
 /// events are delivered.
 ///
-/// This is [dropped] when the event loop is shut down. Note that this only works if you're passing
-/// the entire state to [`EventLoop::run_app`] (passing `&mut app` won't work).
+/// This is [dropped] when the event loop is shut down.
 ///
 /// [the top-level docs]: crate
 /// [`EventLoop::run_app`]: crate::event_loop::EventLoop::run_app

src/changelog/unreleased.md

@@ -194,6 +194,8 @@ changelog entry.
 - Removed `KeyEventExtModifierSupplement`, and made the fields `text_with_all_modifiers` and
   `key_without_modifiers` public on `KeyEvent` instead.
 - Move `window::Fullscreen` to `monitor::Fullscreen`.
+- On web, avoid throwing an exception in `EventLoop::run_app`, instead preferring to return to the caller.
+  This requires passing a `'static` application to ensure that the application state will live as long as necessary.
 
 ### Removed
 
@@ -230,6 +232,8 @@ changelog entry.
 - Remove `CustomCursor::from_rgba`, use `CustomCursorSource` instead.
 - Removed `ApplicationHandler::exited`, the event loop being shut down can now be listened to in
   the `Drop` impl on the application handler.
+- Removed `EventLoopExtWeb::spawn_app`, the exception throwing that made this workaround necessary
+  has been removed from `EventLoop::run_app`.
 
 ### Fixed
 

src/event_loop.rs

@@ -184,7 +184,7 @@ impl EventLoop {
 }
 
 impl EventLoop {
-    /// Run the application with the event loop on the calling thread.
+    /// Run the event loop with the given application on the calling thread.
     ///
     /// ## Event loop flow
     ///
@@ -237,34 +237,70 @@ impl EventLoop {
     /// [`ControlFlow::WaitUntil`] and life-cycle methods like [`ApplicationHandler::resumed`], but
     /// it should give you an idea of how things fit together.
     ///
-    /// ## Platform-specific
+    /// ## Returns
+    ///
+    /// The semantics of this function can be a bit confusing, because the way different platforms
+    /// control their event loop varies significantly.
+    ///
+    /// On most platforms (Android, X11, Wayland, Windows, macOS), this blocks the caller, runs the
+    /// event loop internally, and then returns once [`ActiveEventLoop::exit`] is called.
+    ///
+    /// On iOS, this will register the application handler, and then call [`UIApplicationMain`]
+    /// (which is the only way to run the system event loop), which never returns to the caller
+    /// (the process instead exits after the handler has been dropped).
+    ///
+    /// On the web, this works by registering the application handler, and then immediately
+    /// returning to the caller. This is necessary because WebAssembly (and JavaScript) is always
+    /// executed in the context of the browser's own (internal) event loop, and thus we need to
+    /// return to avoid blocking that and allow events to later be delivered asynchronously.
+    ///
+    /// If you call this function inside `fn main`, you usually do not need to think about these
+    /// details.
+    ///
+    /// [`UIApplicationMain`]: https://developer.apple.com/documentation/uikit/uiapplicationmain(_:_:_:_:)-1yub7?language=objc
     ///
-    /// - **iOS:** Will never return to the caller and so values not passed to this function will
-    ///   *not* be dropped before the process exits.
-    /// - **Web:** Will _act_ as if it never returns to the caller by throwing a Javascript
-    ///   exception (that Rust doesn't see) that will also mean that the rest of the function is
-    ///   never executed and any values not passed to this function will *not* be dropped.
+    /// ## Static
     ///
-    ///   Web applications are recommended to use
+    /// To alleviate the issues noted above, this function requires that you pass in a `'static`
+    /// handler, to ensure that any state your application uses will be alive as long as the
+    /// application is running.
+    ///
+    /// To be clear, you should avoid doing e.g. `event_loop.run_app(&mut app)?`, and prefer
+    /// `event_loop.run_app(app)?` instead.
+    ///
+    /// If this requirement is prohibitive for you, consider using
     #[cfg_attr(
-        web_platform,
-        doc = "  [`EventLoopExtWeb::spawn_app()`][crate::platform::web::EventLoopExtWeb::spawn_app()]"
+        any(
+            windows_platform,
+            macos_platform,
+            android_platform,
+            x11_platform,
+            wayland_platform,
+            docsrs,
+        ),
+        doc = "[`EventLoopExtRunOnDemand::run_app_on_demand`](crate::platform::run_on_demand::EventLoopExtRunOnDemand::run_app_on_demand)"
     )]
-    #[cfg_attr(not(web_platform), doc = "  `EventLoopExtWeb::spawn_app()`")]
-    ///   [^1] instead of [`run_app()`] to avoid the need for the Javascript exception trick, and to
-    ///   make   it clearer that the event loop runs asynchronously (via the browser's own,
-    ///   internal, event   loop) and doesn't block the current thread of execution like it does
-    ///   on other platforms.
-    ///
-    ///   This function won't be available with `target_feature = "exception-handling"`.
+    #[cfg_attr(
+        not(any(
+            windows_platform,
+            macos_platform,
+            android_platform,
+            x11_platform,
+            wayland_platform,
+            docsrs,
+        )),
+        doc = "`EventLoopExtRunOnDemand::run_app_on_demand`"
+    )]
+    /// instead (though note that this is not available on iOS and web).
     ///
-    /// [^1]: `spawn_app()` is only available on the Web platform.
+    /// ## Platform-specific
     ///
-    /// [`set_control_flow()`]: ActiveEventLoop::set_control_flow()
-    /// [`run_app()`]: Self::run_app()
+    /// - **Web** Once your handler has been dropped, it's possible to reinitialize another event
+    ///   loop by calling this function again. This can be useful if you want to recreate the event
+    ///   loop while the WebAssembly module is still loaded. For example, this can be used to
+    ///   recreate the event loop when switching between tabs on a single page application.
     #[inline]
-    #[cfg(not(all(web_platform, target_feature = "exception-handling")))]
-    pub fn run_app<A: ApplicationHandler>(self, app: A) -> Result<(), EventLoopError> {
+    pub fn run_app<A: ApplicationHandler + 'static>(self, app: A) -> Result<(), EventLoopError> {
         self.event_loop.run_app(app)
     }
 

src/platform/run_on_demand.rs

@@ -11,7 +11,7 @@ pub trait EventLoopExtRunOnDemand {
     /// Run the application with the event loop on the calling thread.
     ///
     /// Unlike [`EventLoop::run_app`], this function accepts non-`'static` (i.e. non-`move`)
-    /// closures and it is possible to return control back to the caller without
+    /// state and it is possible to return control back to the caller without
     /// consuming the `EventLoop` (by using [`exit()`]) and
     /// so the event loop can be re-run after it has exit.
     ///
@@ -30,14 +30,7 @@ pub trait EventLoopExtRunOnDemand {
     ///
     /// # Caveats
     /// - This extension isn't available on all platforms, since it's not always possible to return
-    ///   to the caller (specifically this is impossible on iOS and Web - though with the Web
-    ///   backend it is possible to use
-    #[cfg_attr(
-        web_platform,
-        doc = "  [`EventLoopExtWeb::spawn_app()`][crate::platform::web::EventLoopExtWeb::spawn_app()]"
-    )]
-    #[cfg_attr(not(web_platform), doc = "  `EventLoopExtWeb::spawn_app()`")]
-    ///   [^1] more than once instead).
+    ///   to the caller (specifically this is impossible on iOS and Web).
     /// - No [`Window`] state can be carried between separate runs of the event loop.
     ///
     /// You are strongly encouraged to use [`EventLoop::run_app()`] for portability, unless you
@@ -56,8 +49,6 @@ pub trait EventLoopExtRunOnDemand {
     ///   are delivered via callbacks based on an event loop that is internal to the browser itself.
     /// - **iOS:** It's not possible to stop and start an `UIApplication` repeatedly on iOS.
     ///
-    /// [^1]: `spawn_app()` is only available on the Web platforms.
-    ///
     /// [`exit()`]: ActiveEventLoop::exit()
     /// [`set_control_flow()`]: ActiveEventLoop::set_control_flow()
     fn run_app_on_demand<A: ApplicationHandler>(&mut self, app: A) -> Result<(), EventLoopError>;

src/platform/web.rs

@@ -54,7 +54,6 @@ use serde::{Deserialize, Serialize};
 #[cfg(web_platform)]
 use web_sys::HtmlCanvasElement;
 
-use crate::application::ApplicationHandler;
 use crate::cursor::CustomCursorSource;
 use crate::error::NotSupportedError;
 use crate::event_loop::{ActiveEventLoop, EventLoop};
@@ -181,30 +180,6 @@ impl WindowAttributesExtWeb for WindowAttributes {
 
 /// Additional methods on `EventLoop` that are specific to the Web.
 pub trait EventLoopExtWeb {
-    /// Initializes the winit event loop.
-    ///
-    /// Unlike
-    #[cfg_attr(all(web_platform, target_feature = "exception-handling"), doc = "`run_app()`")]
-    #[cfg_attr(
-        not(all(web_platform, target_feature = "exception-handling")),
-        doc = "[`run_app()`]"
-    )]
-    /// [^1], this returns immediately, and doesn't throw an exception in order to
-    /// satisfy its [`!`] return type.
-    ///
-    /// Once the event loop has been destroyed, it's possible to reinitialize another event loop
-    /// by calling this function again. This can be useful if you want to recreate the event loop
-    /// while the WebAssembly module is still loaded. For example, this can be used to recreate the
-    /// event loop when switching between tabs on a single page application.
-    #[rustfmt::skip]
-    ///
-    #[cfg_attr(
-        not(all(web_platform, target_feature = "exception-handling")),
-        doc = "[`run_app()`]: EventLoop::run_app()"
-    )]
-    /// [^1]: `run_app()` is _not_ available on Wasm when the target supports `exception-handling`.
-    fn spawn_app<A: ApplicationHandler + 'static>(self, app: A);
-
     /// Sets the strategy for [`ControlFlow::Poll`].
     ///
     /// See [`PollStrategy`].
@@ -263,10 +238,6 @@ pub trait EventLoopExtWeb {
 }
 
 impl EventLoopExtWeb for EventLoop {
-    fn spawn_app<A: ApplicationHandler + 'static>(self, app: A) {
-        self.event_loop.spawn_app(app);
-    }
-
     fn set_poll_strategy(&self, strategy: PollStrategy) {
         self.event_loop.set_poll_strategy(strategy);
     }

src/platform_impl/apple/uikit/event_loop.rs

@@ -243,7 +243,8 @@ impl EventLoop {
         })
     }
 
-    pub fn run_app<A: ApplicationHandler>(self, app: A) -> ! {
+    // Require `'static` for correctness, we won't be able to `Drop` the user's state otherwise.
+    pub fn run_app<A: ApplicationHandler + 'static>(self, app: A) -> ! {
         let application: Option<Retained<UIApplication>> =
             unsafe { msg_send![UIApplication::class(), sharedApplication] };
         assert!(

src/platform_impl/web/event_loop/mod.rs

@@ -24,32 +24,9 @@ impl EventLoop {
         Ok(EventLoop { elw: ActiveEventLoop::new() })
     }
 
-    pub fn run_app<A: ApplicationHandler>(self, app: A) -> ! {
-        let app = Box::new(app);
-
-        // SAFETY: The `transmute` is necessary because `run()` requires `'static`. This is safe
-        // because this function will never return and all resources not cleaned up by the point we
-        // `throw` will leak, making this actually `'static`.
-        let app = unsafe {
-            std::mem::transmute::<
-                Box<dyn ApplicationHandler + '_>,
-                Box<dyn ApplicationHandler + 'static>,
-            >(app)
-        };
-
-        self.elw.run(app, false);
-
-        // Throw an exception to break out of Rust execution and use unreachable to tell the
-        // compiler this function won't return, giving it a return type of '!'
-        backend::throw(
-            "Using exceptions for control flow, don't mind me. This isn't actually an error!",
-        );
-
-        unreachable!();
-    }
-
-    pub fn spawn_app<A: ApplicationHandler + 'static>(self, app: A) {
-        self.elw.run(Box::new(app), true);
+    pub fn run_app<A: ApplicationHandler + 'static>(self, app: A) -> Result<(), EventLoopError> {
+        self.elw.run(Box::new(app));
+        Ok(())
     }
 
     pub fn window_target(&self) -> &dyn RootActiveEventLoop {

src/platform_impl/web/event_loop/runner.rs

@@ -46,7 +46,6 @@ struct Execution {
     exit: Cell<bool>,
     runner: RefCell<RunnerEnum>,
     suspended: Cell<bool>,
-    event_loop_recreation: Cell<bool>,
     events: RefCell<VecDeque<Event>>,
     id: Cell<usize>,
     window: web_sys::Window,
@@ -193,7 +192,6 @@ impl Shared {
                 exit: Cell::new(false),
                 runner: RefCell::new(RunnerEnum::Pending),
                 suspended: Cell::new(false),
-                event_loop_recreation: Cell::new(false),
                 events: RefCell::new(VecDeque::new()),
                 window,
                 navigator,
@@ -766,9 +764,7 @@ impl Shared {
         // * For each undropped `Window`:
         //     * The `register_redraw_request` closure.
         //     * The `destroy_fn` closure.
-        if self.0.event_loop_recreation.get() {
-            crate::event_loop::EventLoopBuilder::allow_event_loop_recreation();
-        }
+        crate::event_loop::EventLoopBuilder::allow_event_loop_recreation();
     }
 
     // Check if the event loop is currently closed
@@ -807,10 +803,6 @@ impl Shared {
         }
     }
 
-    pub fn event_loop_recreation(&self, allow: bool) {
-        self.0.event_loop_recreation.set(allow)
-    }
-
     pub(crate) fn control_flow(&self) -> ControlFlow {
         self.0.control_flow.get()
     }

src/platform_impl/web/event_loop/window_target.rs

@@ -55,8 +55,7 @@ impl ActiveEventLoop {
         Self { runner: runner::Shared::new(), modifiers: ModifiersShared::default() }
     }
 
-    pub(crate) fn run(&self, app: Box<dyn ApplicationHandler>, event_loop_recreation: bool) {
-        self.runner.event_loop_recreation(event_loop_recreation);
+    pub(crate) fn run(&self, app: Box<dyn ApplicationHandler>) {
         self.runner.start(app, self.clone());
     }
 

src/platform_impl/web/web_sys/mod.rs

@@ -25,10 +25,6 @@ pub use self::safe_area::SafeAreaHandle;
 pub use self::schedule::Schedule;
 use crate::dpi::{LogicalPosition, LogicalSize};
 
-pub fn throw(msg: &str) {
-    wasm_bindgen::throw_str(msg);
-}
-
 pub struct PageTransitionEventHandle {
     _show_listener: event_handle::EventListenerHandle<dyn FnMut(PageTransitionEvent)>,
     _hide_listener: event_handle::EventListenerHandle<dyn FnMut(PageTransitionEvent)>,