winit/event_loop: Add register_app and run_app_never_return

To allow users to explicitly choose the run semantics that they want.

winit-core/src/event_loop/mod.rs

@@ -1,4 +1,6 @@
+pub mod never_return;
 pub mod pump_events;
+pub mod register;
 pub mod run_on_demand;
 
 use std::fmt::{self, Debug};

winit-core/src/event_loop/never_return.rs

@@ -0,0 +1,14 @@
+use crate::application::ApplicationHandler;
+
+/// Additional methods on `EventLoop` for platforms whose run method never return.
+pub trait EventLoopExtNeverReturn {
+    /// Run the event loop and call `process::exit` once finished.
+    ///
+    /// ## Platform-specific
+    ///
+    /// - **iOS**: This registers the callbacks with the system and calls `UIApplicationMain`.
+    /// - **macOS**: Unimplemented (TODO: Should call `NSApplicationMain`).
+    /// - **Android/Orbital/Wayland/Windows/X11**: Unsupported.
+    /// - **Web**: Impossible to support properly.
+    fn run_app_never_return<A: ApplicationHandler + 'static>(self, app: A) -> !;
+}

winit-core/src/event_loop/register.rs

@@ -0,0 +1,17 @@
+use crate::application::ApplicationHandler;
+
+/// Additional methods on `EventLoop` that registers it with the system event loop.
+pub trait EventLoopExtRegister {
+    /// Initialize and register the application with the system's event loop, such that the
+    /// callbacks will be run later.
+    ///
+    /// ## Platform-specific
+    ///
+    /// - **Web**: 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.
+    /// - **iOS/macOS**: Unimplemented.
+    /// - **Android/Orbital/Wayland/Windows/X11**: Unsupported.
+    fn register_app<A: ApplicationHandler + 'static>(self, app: A);
+}

winit-core/src/event_loop/run_on_demand.rs

@@ -6,15 +6,13 @@ use crate::{
     window::Window,
 };
 
-#[allow(rustdoc::broken_intra_doc_links)] // FIXME(madsmtm): Fix these.
 /// Additional methods on [`EventLoop`] to return control flow to the caller.
 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`)
-    /// 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.
+    /// 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.
     ///
     /// It's expected that each run of the loop will be for orthogonal instantiations of your
     /// Winit application, but internally each instantiation may re-use some common window