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 f88fba0253b45de6a2ac0c3cbcf01f50503c9396.

* Change Exit to ExitWithCode and make an Exit const

* Revert "Add exit code example"

This reverts commit fbd3d03de9c2d7516c7a63da489c99f498b710df.

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

This reverts commit daabcdf9ef9e16acad715c094ae442529e39fcbc.

* Revert "Fix examples to have an exit code"

This reverts commit 0df486896b8d106acf65ba83c45cc88d60d228e1.

* 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/macos/app_state.rs

@@ -62,7 +62,6 @@ pub trait EventHandler: Debug {
 
 struct EventLoopHandler<T: 'static> {
     callback: Weak<RefCell<dyn FnMut(Event<'_, T>, &RootWindowTarget<T>, &mut ControlFlow)>>,
-    will_exit: bool,
     window_target: Rc<RootWindowTarget<T>>,
 }
 
@@ -98,25 +97,25 @@ impl<T> Debug for EventLoopHandler<T> {
 impl<T> EventHandler for EventLoopHandler<T> {
     fn handle_nonuser_event(&mut self, event: Event<'_, Never>, control_flow: &mut ControlFlow) {
         self.with_callback(|this, mut callback| {
-            (callback)(event.userify(), &this.window_target, control_flow);
-            this.will_exit |= *control_flow == ControlFlow::Exit;
-            if this.will_exit {
-                *control_flow = ControlFlow::Exit;
+            if let ControlFlow::ExitWithCode(code) = *control_flow {
+                let dummy = &mut ControlFlow::ExitWithCode(code);
+                (callback)(event.userify(), &this.window_target, dummy);
+            } else {
+                (callback)(event.userify(), &this.window_target, control_flow);
             }
         });
     }
 
     fn handle_user_events(&mut self, control_flow: &mut ControlFlow) {
         self.with_callback(|this, mut callback| {
-            let mut will_exit = this.will_exit;
             for event in this.window_target.p.receiver.try_iter() {
-                (callback)(Event::UserEvent(event), &this.window_target, control_flow);
-                will_exit |= *control_flow == ControlFlow::Exit;
-                if will_exit {
-                    *control_flow = ControlFlow::Exit;
+                if let ControlFlow::ExitWithCode(code) = *control_flow {
+                    let dummy = &mut ControlFlow::ExitWithCode(code);
+                    (callback)(Event::UserEvent(event), &this.window_target, dummy);
+                } else {
+                    (callback)(Event::UserEvent(event), &this.window_target, control_flow);
                 }
             }
-            this.will_exit = will_exit;
         });
     }
 }
@@ -160,7 +159,10 @@ impl Handler {
     }
 
     fn should_exit(&self) -> bool {
-        *self.control_flow.lock().unwrap() == ControlFlow::Exit
+        matches!(
+            *self.control_flow.lock().unwrap(),
+            ControlFlow::ExitWithCode(_)
+        )
     }
 
     fn get_control_flow_and_update_prev(&self) -> ControlFlow {
@@ -268,16 +270,20 @@ impl AppState {
     ) {
         *HANDLER.callback.lock().unwrap() = Some(Box::new(EventLoopHandler {
             callback,
-            will_exit: false,
             window_target,
         }));
     }
 
-    pub fn exit() {
+    pub fn exit() -> i32 {
         HANDLER.set_in_callback(true);
         HANDLER.handle_nonuser_event(EventWrapper::StaticEvent(Event::LoopDestroyed));
         HANDLER.set_in_callback(false);
         HANDLER.callback.lock().unwrap().take();
+        if let ControlFlow::ExitWithCode(code) = HANDLER.get_old_and_new_control_flow().1 {
+            code
+        } else {
+            0
+        }
     }
 
     pub fn launched(app_delegate: &Object) {
@@ -332,7 +338,7 @@ impl AppState {
                     }
                 }
             }
-            ControlFlow::Exit => StartCause::Poll, //panic!("unexpected `ControlFlow::Exit`"),
+            ControlFlow::ExitWithCode(_) => StartCause::Poll, //panic!("unexpected `ControlFlow::Exit`"),
         };
         HANDLER.set_in_callback(true);
         HANDLER.handle_nonuser_event(EventWrapper::StaticEvent(Event::NewEvents(cause)));
@@ -435,7 +441,7 @@ impl AppState {
         }
         HANDLER.update_start_time();
         match HANDLER.get_old_and_new_control_flow() {
-            (ControlFlow::Exit, _) | (_, ControlFlow::Exit) => (),
+            (ControlFlow::ExitWithCode(_), _) | (_, ControlFlow::ExitWithCode(_)) => (),
             (old, new) if old == new => (),
             (_, ControlFlow::Wait) => HANDLER.waker().stop(),
             (_, ControlFlow::WaitUntil(instant)) => HANDLER.waker().start_at(instant),

src/platform_impl/macos/event_loop.rs

@@ -155,11 +155,11 @@ impl<T> EventLoop<T> {
     where
         F: 'static + FnMut(Event<'_, T>, &RootWindowTarget<T>, &mut ControlFlow),
     {
-        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, callback: F)
+    pub fn run_return<F>(&mut self, callback: F) -> i32
     where
         F: FnMut(Event<'_, T>, &RootWindowTarget<T>, &mut ControlFlow),
     {
@@ -176,7 +176,7 @@ impl<T> EventLoop<T> {
 
         self._callback = Some(Rc::clone(&callback));
 
-        autoreleasepool(|| unsafe {
+        let exit_code = autoreleasepool(|| unsafe {
             let app = NSApp();
             assert_ne!(app, nil);
 
@@ -192,9 +192,11 @@ impl<T> EventLoop<T> {
                 drop(self._callback.take());
                 resume_unwind(panic);
             }
-            AppState::exit();
+            AppState::exit()
         });
         drop(self._callback.take());
+
+        exit_code
     }
 
     pub fn create_proxy(&self) -> Proxy<T> {