Re-work event loop run() API so it can return a Result

This re-works the portable `run()` API that consumes the `EventLoop` and
runs the loop on the calling thread until the app exits.

This can be supported across _all_ platforms and compared to the
previous `run() -> !` API is now able to return a `Result` status on all
platforms except iOS and Web. Fixes: #2709

By moving away from `run() -> !` we stop calling `std::process::exit()`
internally as a means to kill the process without returning which means
it's possible to return an exit status and applications can return from
their `main()` function normally.

This also fixes Android support where an Activity runs in a thread but
we can't assume to have full ownership of the process (other services
could be running in separate threads).

Additionally all examples have generally been updated so that `main()`
returns a `Result` from `run()`

Fixes: #2709

examples/startup_notification.rs

@@ -1,9 +1,5 @@
 //! Demonstrates the use of startup notifications on Linux.
 
-fn main() {
-    example::main();
-}
-
 #[cfg(any(x11_platform, wayland_platform))]
 #[path = "./util/fill.rs"]
 mod fill;
@@ -21,7 +17,7 @@ mod example {
     };
     use winit::window::{Window, WindowBuilder, WindowId};
 
-    pub(super) fn main() {
+    pub(super) fn main() -> Result<(), impl std::error::Error> {
         // Create the event loop and get the activation token.
         let event_loop = EventLoop::new();
         let mut current_token = match event_loop.read_token_from_env() {
@@ -115,13 +111,16 @@ mod example {
             }
 
             flow.set_wait();
-        });
+        })
     }
 }
 
-#[cfg(not(any(x11_platform, wayland_platform)))]
-mod example {
-    pub(super) fn main() {
-        println!("This example is only supported on X11 and Wayland platforms.");
-    }
+#[cfg(any(x11_platform, wayland_platform))]
+fn main() -> Result<(), impl std::error::Error> {
+    example::main()
+}
+
+#[cfg(not(any(x11_platform, wayland_platform)))]
+fn main() {
+    println!("This example is only supported on X11 and Wayland platforms.");
 }