Add exit code to ControlFlow::Exit (#2100)

* Add exit code to control flow and impl on linux

* Fix examples to have an exit code

* Fix doc examples to use an exit code

* Improve documentation wording on the exit code

* Add exit code example

* Add exit code on windows

* Change i32 as exit code to u8

This avoids nasty surprises with negative numbers on some unix-alikes
due to two's complement.

* Fix android usages of ControlFlow::Exit

* Fix ios usages of ControlFlow::Exit

* Fix web usages of ControlFlow::Exit

* Add macos exit code

* Add changelog note

* Document exit code on display server disconnection

* Revert "Change i32 as exit code to u8"

This reverts commit f88fba0253.

* Change Exit to ExitWithCode and make an Exit const

* Revert "Add exit code example"

This reverts commit fbd3d03de9.

* Revert "Fix doc examples to use an exit code"

This reverts commit daabcdf9ef.

* Revert "Fix examples to have an exit code"

This reverts commit 0df486896b.

* Fix unix-alike to use ExitWithCode instead of Exit

* Fix windows to use ExitWithCode rather than Exit

* Silence warning about non-uppercase Exit const

* Refactor exit code handling

* Fix macos Exit usage and recover original semantic

* Fix ios to use ExitWithCode instead of Exit

* Update documentation to reflect ExitWithCode

* Fix web to use ExitWithCode when needed, not Exit

* Fix android to use ExitWithCode, not Exit

* Apply documenation nits

* Apply even more documentation nits

* Move change in CHANGELOG.md under "Unreleased"

* Try to use OS error code as exit code on wayland

src/platform_impl/linux/mod.rs

@@ -655,7 +655,7 @@ impl<T: 'static> EventLoop<T> {
         x11_or_wayland!(match self; EventLoop(evlp) => evlp.create_proxy(); as EventLoopProxy)
     }
 
-    pub fn run_return<F>(&mut self, callback: F)
+    pub fn run_return<F>(&mut self, callback: F) -> i32
     where
         F: FnMut(crate::event::Event<'_, T>, &RootELW<T>, &mut ControlFlow),
     {
@@ -741,16 +741,13 @@ fn sticky_exit_callback<T, F>(
 ) where
     F: FnMut(Event<'_, T>, &RootELW<T>, &mut ControlFlow),
 {
-    // make ControlFlow::Exit sticky by providing a dummy
-    // control flow reference if it is already Exit.
-    let mut dummy = ControlFlow::Exit;
-    let cf = if *control_flow == ControlFlow::Exit {
-        &mut dummy
+    // make ControlFlow::ExitWithCode sticky by providing a dummy
+    // control flow reference if it is already ExitWithCode.
+    if let ControlFlow::ExitWithCode(code) = *control_flow {
+        callback(evt, target, &mut ControlFlow::ExitWithCode(code))
     } else {
-        control_flow
-    };
-    // user callback
-    callback(evt, target, cf)
+        callback(evt, target, control_flow)
+    }
 }
 
 fn assert_is_main_thread(suggested_method: &str) {

src/platform_impl/linux/wayland/event_loop/mod.rs

@@ -206,11 +206,11 @@ impl<T: 'static> EventLoop<T> {
     where
         F: FnMut(Event<'_, T>, &RootEventLoopWindowTarget<T>, &mut ControlFlow) + 'static,
     {
-        self.run_return(callback);
-        process::exit(0)
+        let exit_code = self.run_return(callback);
+        process::exit(exit_code);
     }
 
-    pub fn run_return<F>(&mut self, mut callback: F)
+    pub fn run_return<F>(&mut self, mut callback: F) -> i32
     where
         F: FnMut(Event<'_, T>, &RootEventLoopWindowTarget<T>, &mut ControlFlow),
     {
@@ -235,7 +235,8 @@ impl<T: 'static> EventLoop<T> {
         // really an option. Instead we inform that the event loop got destroyed. We may
         // communicate an error that something was terminated, but winit doesn't provide us
         // with an API to do that via some event.
-        loop {
+        // Still, we set the exit code to the error's OS error code, or to 1 if not possible.
+        let exit_code = loop {
             // Handle pending user events. We don't need back buffer, since we can't dispatch
             // user events indirectly via callback to the user.
             for user_event in pending_user_events.borrow_mut().drain(..) {
@@ -431,20 +432,19 @@ impl<T: 'static> EventLoop<T> {
                     _ => unreachable!(),
                 };
 
-                if let Ok(dispatched) = queue.dispatch_pending(state, |_, _, _| unimplemented!()) {
-                    dispatched > 0
-                } else {
-                    break;
+                match queue.dispatch_pending(state, |_, _, _| unimplemented!()) {
+                    Ok(dispatched) => dispatched > 0,
+                    Err(error) => break error.raw_os_error().unwrap_or(1),
                 }
             };
 
             match control_flow {
-                ControlFlow::Exit => break,
+                ControlFlow::ExitWithCode(code) => break code,
                 ControlFlow::Poll => {
                     // Non-blocking dispatch.
                     let timeout = Duration::from_millis(0);
-                    if self.loop_dispatch(Some(timeout)).is_err() {
-                        break;
+                    if let Err(error) = self.loop_dispatch(Some(timeout)) {
+                        break error.raw_os_error().unwrap_or(1);
                     }
 
                     callback(
@@ -460,8 +460,8 @@ impl<T: 'static> EventLoop<T> {
                         None
                     };
 
-                    if self.loop_dispatch(timeout).is_err() {
-                        break;
+                    if let Err(error) = self.loop_dispatch(timeout) {
+                        break error.raw_os_error().unwrap_or(1);
                     }
 
                     callback(
@@ -483,8 +483,8 @@ impl<T: 'static> EventLoop<T> {
                         Duration::from_millis(0)
                     };
 
-                    if self.loop_dispatch(Some(duration)).is_err() {
-                        break;
+                    if let Err(error) = self.loop_dispatch(Some(duration)) {
+                        break error.raw_os_error().unwrap_or(1);
                     }
 
                     let now = Instant::now();
@@ -510,9 +510,10 @@ impl<T: 'static> EventLoop<T> {
                     }
                 }
             }
-        }
+        };
 
         callback(Event::LoopDestroyed, &self.window_target, &mut control_flow);
+        exit_code
     }
 
     #[inline]

src/platform_impl/linux/x11/mod.rs

@@ -258,7 +258,7 @@ impl<T: 'static> EventLoop<T> {
         &self.target
     }
 
-    pub fn run_return<F>(&mut self, mut callback: F)
+    pub fn run_return<F>(&mut self, mut callback: F) -> i32
     where
         F: FnMut(Event<'_, T>, &RootELW<T>, &mut ControlFlow),
     {
@@ -266,7 +266,7 @@ impl<T: 'static> EventLoop<T> {
         let mut events = Events::with_capacity(8);
         let mut cause = StartCause::Init;
 
-        loop {
+        let exit_code = loop {
             sticky_exit_callback(
                 crate::event::Event::NewEvents(cause),
                 &self.target,
@@ -329,7 +329,7 @@ impl<T: 'static> EventLoop<T> {
             let (deadline, timeout);
 
             match control_flow {
-                ControlFlow::Exit => break,
+                ControlFlow::ExitWithCode(code) => break code,
                 ControlFlow::Poll => {
                     cause = StartCause::Poll;
                     deadline = None;
@@ -376,21 +376,22 @@ impl<T: 'static> EventLoop<T> {
                     requested_resume: deadline,
                 };
             }
-        }
+        };
 
         callback(
             crate::event::Event::LoopDestroyed,
             &self.target,
             &mut control_flow,
         );
+        exit_code
     }
 
     pub fn run<F>(mut self, callback: F) -> !
     where
         F: 'static + FnMut(Event<'_, T>, &RootELW<T>, &mut ControlFlow),
     {
-        self.run_return(callback);
-        ::std::process::exit(0);
+        let exit_code = self.run_return(callback);
+        ::std::process::exit(exit_code);
     }
 
     fn drain_events<F>(&mut self, callback: &mut F, control_flow: &mut ControlFlow)