Re-work event loop run APIs

Overall this re-works the APIs for how an `EventLoop` is run to cover
these use-cases, with varying portability caveats:

1. A 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: rust-windowing#2709
2. A less portable `run_ondmand()` API that covers the use case in rust-windowing#2431
   where applications need to be able to re-run a Winit application
   multiple times against a persistent `EventLoop`. This doesn't allow
   `Window` state to carry across separate runs of the loop, but does
   allow orthogonal re-instantiations of a gui application.

   Available On: Windows, Linux, MacOS
   Could be supported on Android if there's a use case
   Incompatible with iOS, Web
   Fixes: rust-windowing#2431
3. A less portable (and on MacOS, likely less-optimal) `pump_events()`
   API that covers the use case in rust-windowing#2706 and allows a Winit event loop to
   be embedded within an external `loop {}`. Applications call `pump_events()`
   once per iteration of their own external loop to dispatch all pending Winit
   events, without blocking the external loop.

   Available On: Windows, Linux, MacOS, Android
   Incompatible With: iOS, Web
   Fixes: rust-windowing#2706

Each method of running the loop will behave consistently in terms of how
`NewEvents(Init)`, `Resumed` and `LoopDestroyed` events are dispatched
(so portable application code wouldn't necessarily need to have any awareness
of which method of running the loop was being used)

In particular 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).

`run_return` has been removed, and the overlapping use cases that
`run_return` previously partially aimed to support have been split
across `run_ondemand` and `pump_events`.

To help test the changes this adds:
  examples/window_ondemand
  examples/window_pump_events
  examples/window_pump_events_rfd

The last _rfd example, tests the interaction between the `rfd` crate and
using `pump_events` to embed Winit within an external event loop.

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

Fixes: rust-windowing#2709
Fixes: rust-windowing#2706
Fixes: rust-windowing#2431
Fixes: rust-windowing#2752

TODO: tidy up macos changes - probably lots of debug stuff left in atm
TODO: Linux
TODO: ask someone to test orbital changes, made blindly
TODO: split patch up

Cargo.toml

@@ -60,6 +60,7 @@ serde = { version = "1", optional = true, features = ["serde_derive"] }
 [dev-dependencies]
 image = { version = "0.24.0", default-features = false, features = ["png"] }
 simple_logger = { version = "2.1.0", default_features = false }
+rfd = { version = "0.11.0" }
 
 [target.'cfg(target_os = "android")'.dependencies]
 # Coordinate the next winit release with android-ndk-rs: https://github.com/rust-windowing/winit/issues/1995

examples/control_flow.rs

@@ -19,7 +19,7 @@ enum Mode {
 const WAIT_TIME: time::Duration = time::Duration::from_millis(100);
 const POLL_SLEEP_TIME: time::Duration = time::Duration::from_millis(100);
 
-fn main() {
+fn main() -> std::result::Result<(), impl std::error::Error> {
     SimpleLogger::new().init().unwrap();
 
     println!("Press '1' to switch to Wait mode.");
@@ -110,5 +110,5 @@ fn main() {
             }
             _ => (),
         }
-    });
+    })
 }

examples/cursor.rs

@@ -7,7 +7,7 @@ use winit::{
     window::{CursorIcon, WindowBuilder},
 };
 
-fn main() {
+fn main() -> std::result::Result<(), impl std::error::Error> {
     SimpleLogger::new().init().unwrap();
     let event_loop = EventLoop::new();
 
@@ -48,7 +48,7 @@ fn main() {
             }
             _ => (),
         }
-    });
+    })
 }
 
 const CURSORS: &[CursorIcon] = &[

examples/cursor_grab.rs

@@ -7,7 +7,7 @@ use winit::{
     window::{CursorGrabMode, WindowBuilder},
 };
 
-fn main() {
+fn main() -> std::result::Result<(), impl std::error::Error> {
     SimpleLogger::new().init().unwrap();
     let event_loop = EventLoop::new();
 
@@ -66,5 +66,5 @@ fn main() {
             },
             _ => (),
         }
-    });
+    })
 }

examples/custom_events.rs

@@ -1,7 +1,7 @@
 #![allow(clippy::single_match)]
 
 #[cfg(not(wasm_platform))]
-fn main() {
+fn main() -> std::result::Result<(), impl std::error::Error> {
     use simple_logger::SimpleLogger;
     use winit::{
         event::{Event, WindowEvent},
@@ -46,7 +46,7 @@ fn main() {
             } => control_flow.set_exit(),
             _ => (),
         }
-    });
+    })
 }
 
 #[cfg(wasm_platform)]

examples/drag_window.rs

@@ -9,7 +9,7 @@ use winit::{
     window::{Window, WindowBuilder, WindowId},
 };
 
-fn main() {
+fn main() -> std::result::Result<(), impl std::error::Error> {
     SimpleLogger::new().init().unwrap();
     let event_loop = EventLoop::new();
 
@@ -60,7 +60,7 @@ fn main() {
             _ => (),
         },
         _ => (),
-    });
+    })
 }
 
 fn name_windows(window_id: WindowId, switched: bool, window_1: &Window, window_2: &Window) {

examples/fullscreen.rs

@@ -8,7 +8,7 @@ use winit::window::{Fullscreen, WindowBuilder};
 #[cfg(target_os = "macos")]
 use winit::platform::macos::WindowExtMacOS;
 
-fn main() {
+fn main() -> std::result::Result<(), impl std::error::Error> {
     SimpleLogger::new().init().unwrap();
     let event_loop = EventLoop::new();
 
@@ -118,5 +118,5 @@ fn main() {
             },
             _ => {}
         }
-    });
+    })
 }

examples/handling_close.rs

@@ -7,7 +7,7 @@ use winit::{
     window::WindowBuilder,
 };
 
-fn main() {
+fn main() -> std::result::Result<(), impl std::error::Error> {
     SimpleLogger::new().init().unwrap();
     let event_loop = EventLoop::new();
 
@@ -82,5 +82,5 @@ fn main() {
             }
             _ => (),
         }
-    });
+    })
 }

examples/ime.rs

@@ -9,7 +9,7 @@ use winit::{
     window::{ImePurpose, WindowBuilder},
 };
 
-fn main() {
+fn main() -> std::result::Result<(), impl std::error::Error> {
     SimpleLogger::new()
         .with_level(LevelFilter::Trace)
         .init()
@@ -108,5 +108,5 @@ fn main() {
             }
             _ => (),
         }
-    });
+    })
 }

examples/mouse_wheel.rs

@@ -7,7 +7,7 @@ use winit::{
     window::WindowBuilder,
 };
 
-fn main() {
+fn main() -> std::result::Result<(), impl std::error::Error> {
     SimpleLogger::new().init().unwrap();
     let event_loop = EventLoop::new();
 
@@ -58,5 +58,5 @@ In other words, the deltas indicate the direction in which to move the content (
             },
             _ => (),
         }
-    });
+    })
 }

examples/multithreaded.rs

@@ -1,7 +1,7 @@
 #![allow(clippy::single_match)]
 
 #[cfg(not(wasm_platform))]
-fn main() {
+fn main() -> std::result::Result<(), impl std::error::Error> {
     use std::{collections::HashMap, sync::mpsc, thread, time::Duration};
 
     use simple_logger::SimpleLogger;

examples/multiwindow.rs

@@ -9,7 +9,7 @@ use winit::{
     window::Window,
 };
 
-fn main() {
+fn main() -> std::result::Result<(), impl std::error::Error> {
     SimpleLogger::new().init().unwrap();
     let event_loop = EventLoop::new();
 

examples/request_redraw.rs

@@ -7,7 +7,7 @@ use winit::{
     window::WindowBuilder,
 };
 
-fn main() {
+fn main() -> std::result::Result<(), impl std::error::Error> {
     SimpleLogger::new().init().unwrap();
     let event_loop = EventLoop::new();
 
@@ -37,5 +37,5 @@ fn main() {
             }
             _ => (),
         }
-    });
+    })
 }

examples/request_redraw_threaded.rs

@@ -1,7 +1,7 @@
 #![allow(clippy::single_match)]
 
 #[cfg(not(wasm_platform))]
-fn main() {
+fn main() -> std::result::Result<(), impl std::error::Error> {
     use std::{thread, time};
 
     use simple_logger::SimpleLogger;
@@ -39,7 +39,7 @@ fn main() {
             }
             _ => (),
         }
-    });
+    })
 }
 
 #[cfg(wasm_platform)]

examples/resizable.rs

@@ -8,7 +8,7 @@ use winit::{
     window::WindowBuilder,
 };
 
-fn main() {
+fn main() -> std::result::Result<(), impl std::error::Error> {
     SimpleLogger::new().init().unwrap();
     let event_loop = EventLoop::new();
 
@@ -46,5 +46,5 @@ fn main() {
             },
             _ => (),
         };
-    });
+    })
 }

examples/theme.rs

@@ -7,7 +7,7 @@ use winit::{
     window::{Theme, WindowBuilder},
 };
 
-fn main() {
+fn main() -> std::result::Result<(), impl std::error::Error> {
     SimpleLogger::new().init().unwrap();
     let event_loop = EventLoop::new();
 
@@ -67,5 +67,5 @@ fn main() {
             },
             _ => (),
         }
-    });
+    })
 }

examples/timer.rs

@@ -10,7 +10,7 @@ use winit::{
     window::WindowBuilder,
 };
 
-fn main() {
+fn main() -> std::result::Result<(), impl std::error::Error> {
     SimpleLogger::new().init().unwrap();
     let event_loop = EventLoop::new();
 
@@ -38,5 +38,5 @@ fn main() {
             } => control_flow.set_exit(),
             _ => (),
         }
-    });
+    })
 }

examples/touchpad_gestures.rs

@@ -5,7 +5,7 @@ use winit::{
     window::WindowBuilder,
 };
 
-fn main() {
+fn main() -> std::result::Result<(), impl std::error::Error> {
     SimpleLogger::new().init().unwrap();
     let event_loop = EventLoop::new();
 
@@ -42,5 +42,5 @@ fn main() {
                 _ => (),
             }
         }
-    });
+    })
 }

examples/transparent.rs

@@ -7,7 +7,7 @@ use winit::{
     window::WindowBuilder,
 };
 
-fn main() {
+fn main() -> std::result::Result<(), impl std::error::Error> {
     SimpleLogger::new().init().unwrap();
     let event_loop = EventLoop::new();
 
@@ -30,5 +30,5 @@ fn main() {
             } => control_flow.set_exit(),
             _ => (),
         }
-    });
+    })
 }

examples/web.rs

@@ -6,7 +6,7 @@ use winit::{
     window::WindowBuilder,
 };
 
-pub fn main() {
+pub fn main() -> std::result::Result<(), impl std::error::Error> {
     let event_loop = EventLoop::new();
 
     let window = WindowBuilder::new()
@@ -33,7 +33,7 @@ pub fn main() {
             }
             _ => (),
         }
-    });
+    })
 }
 
 #[cfg(wasm_platform)]

examples/window.rs

@@ -7,7 +7,7 @@ use winit::{
     window::WindowBuilder,
 };
 
-fn main() {
+fn main() -> Result<(), impl std::error::Error> {
     SimpleLogger::new().init().unwrap();
     let event_loop = EventLoop::new();
 
@@ -31,5 +31,5 @@ fn main() {
             }
             _ => (),
         }
-    });
+    })
 }

examples/window_buttons.rs

@@ -10,7 +10,7 @@ use winit::{
     window::{WindowBuilder, WindowButtons},
 };
 
-fn main() {
+fn main() -> std::result::Result<(), impl std::error::Error> {
     SimpleLogger::new().init().unwrap();
     let event_loop = EventLoop::new();
 
@@ -64,5 +64,5 @@ fn main() {
             } if window_id == window.id() => control_flow.set_exit(),
             _ => (),
         }
-    });
+    })
 }

examples/window_debug.rs

@@ -10,7 +10,7 @@ use winit::{
     window::{Fullscreen, WindowBuilder},
 };
 
-fn main() {
+fn main() -> std::result::Result<(), impl std::error::Error> {
     SimpleLogger::new().init().unwrap();
     let event_loop = EventLoop::new();
 
@@ -128,5 +128,5 @@ fn main() {
             } if window_id == window.id() => control_flow.set_exit(),
             _ => (),
         }
-    });
+    })
 }

examples/window_icon.rs

@@ -9,7 +9,7 @@ use winit::{
     window::{Icon, WindowBuilder},
 };
 
-fn main() {
+fn main() -> std::result::Result<(), impl std::error::Error> {
     SimpleLogger::new().init().unwrap();
 
     // You'll have to choose an icon size at your own discretion. On X11, the desired size varies
@@ -43,7 +43,7 @@ fn main() {
                 _ => (),
             }
         }
-    });
+    })
 }
 
 fn load_icon(path: &Path) -> Icon {