Include a error code in AppExit

Author: Brezak

crates/bevy_app/src/app.rs

@@ -13,11 +13,14 @@ use bevy_ecs::{
 #[cfg(feature = "trace")]
 use bevy_utils::tracing::info_span;
 use bevy_utils::{tracing::debug, HashMap};
-use std::panic::{catch_unwind, resume_unwind, AssertUnwindSafe};
 use std::{
     fmt::Debug,
     process::{ExitCode, Termination},
 };
+use std::{
+    num::NonZeroU8,
+    panic::{catch_unwind, resume_unwind, AssertUnwindSafe},
+};
 use thiserror::Error;
 
 bevy_ecs::define_label!(
@@ -852,6 +855,39 @@ impl App {
         self.main_mut().ignore_ambiguity(schedule, a, b);
         self
     }
+
+    /// Attempts to determine if an [`AppExit`] was raised since the last update.
+    ///
+    /// Will attempt to return the first [`Error`](AppExit::Error) it encounters.
+    pub fn should_exit(&self) -> Option<AppExit> {
+        let mut reader = ManualEventReader::default();
+
+        self.should_exit_manual(&mut reader)
+    }
+
+    /// Several app runners in this crate keep their own [`ManualEventReader<AppExit>`].
+    /// This exists to accommodate them.
+    pub(crate) fn should_exit_manual(
+        &self,
+        reader: &mut ManualEventReader<AppExit>,
+    ) -> Option<AppExit> {
+        let Some(events) = self.world().get_resource::<Events<AppExit>>() else {
+            return None;
+        };
+
+        let mut events = reader.read(events);
+
+        if events.len() != 0 {
+            return Some(
+                events
+                    .find(|exit| exit.is_error())
+                    .cloned()
+                    .unwrap_or(AppExit::Success),
+            );
+        }
+
+        None
+    }
 }
 
 type RunnerFn = Box<dyn FnOnce(App) -> AppExit>;
@@ -870,9 +906,9 @@ fn run_once(mut app: App) -> AppExit {
     if let Some(app_exit_events) = app.world().get_resource::<Events<AppExit>>() {
         if exit_code_reader
             .read(app_exit_events)
-            .any(|exit| *exit == AppExit::Error)
+            .any(AppExit::is_error)
         {
-            return AppExit::Error;
+            return AppExit::error();
         }
     }
 
@@ -890,21 +926,62 @@ pub enum AppExit {
     #[default]
     Success,
     /// The [`App`] experienced an unhandleable error.
-    Error,
+    /// Holds the exit code we expect our app to return.
+    Error(NonZeroU8),
+}
+
+impl AppExit {
+    /// Creates a [`AppExit::Error`] with a error code of 1.
+    #[must_use]
+    pub fn error() -> Self {
+        Self::Error(NonZeroU8::MIN)
+    }
+
+    /// Returns `true` if `self` is a [`AppExit::Success`].
+    #[must_use]
+    pub fn is_success(&self) -> bool {
+        matches!(self, AppExit::Success)
+    }
+
+    /// Returns `true` if `self` is a [`AppExit::Error`].
+    #[must_use]
+    pub fn is_error(&self) -> bool {
+        matches!(self, AppExit::Error(_))
+    }
+
+    /// Creates a [`AppExit`] from a code.
+    ///
+    /// When code is 0 a [`AppExit::Success`] is constructed otherwise a
+    /// [`AppExit::Error`] is constructed.
+    #[must_use]
+    pub fn from_code(code: u8) -> Self {
+        match NonZeroU8::new(code) {
+            Some(code) => Self::Error(code),
+            None => Self::Success,
+        }
+    }
+}
+
+impl From<u8> for AppExit {
+    #[must_use]
+    fn from(value: u8) -> Self {
+        Self::from_code(value)
+    }
 }
 
 impl Termination for AppExit {
     fn report(self) -> std::process::ExitCode {
         match self {
             AppExit::Success => ExitCode::SUCCESS,
-            AppExit::Error => ExitCode::FAILURE,
+            // We leave logging an error to our users
+            AppExit::Error(value) => ExitCode::from(value.get()),
         }
     }
 }
 
 #[cfg(test)]
 mod tests {
-    use std::marker::PhantomData;
+    use std::{marker::PhantomData, mem};
 
     use bevy_ecs::{
         schedule::{OnEnter, States},
@@ -1112,7 +1189,7 @@ mod tests {
     /// fix: <https://github.com/bevyengine/bevy/pull/10389>
     #[test]
     fn regression_test_10385() {
-        use super::{AppExit, Res, Resource};
+        use super::{Res, Resource};
         use crate::PreUpdate;
 
         #[derive(Resource)]
@@ -1139,4 +1216,11 @@ mod tests {
             .add_systems(PreUpdate, my_system)
             .run();
     }
+
+    #[test]
+    fn app_exit_size() {
+        // There wont be many of them so the size isn't a issue but
+        // it's nice they're so small let's keep it that way.
+        assert_eq!(mem::size_of::<AppExit>(), mem::size_of::<u8>());
+    }
 }

crates/bevy_app/src/schedule_runner.rs

@@ -3,7 +3,7 @@ use crate::{
     plugin::Plugin,
     PluginsState,
 };
-use bevy_ecs::event::{Events, ManualEventReader};
+use bevy_ecs::event::ManualEventReader;
 use bevy_utils::{Duration, Instant};
 
 #[cfg(target_arch = "wasm32")]
@@ -87,14 +87,8 @@ impl Plugin for ScheduleRunnerPlugin {
                 RunMode::Once => {
                     app.update();
 
-                    let mut exit_code_reader = ManualEventReader::default();
-                    if let Some(app_exit_events) = app.world().get_resource::<Events<AppExit>>() {
-                        if exit_code_reader
-                            .read(app_exit_events)
-                            .any(|exit| *exit == AppExit::Error)
-                        {
-                            return AppExit::Error;
-                        }
+                    if let Some(exit) = app.should_exit_manual(&mut app_exit_event_reader) {
+                        return exit;
                     }
 
                     AppExit::Success
@@ -107,12 +101,9 @@ impl Plugin for ScheduleRunnerPlugin {
 
                         app.update();
 
-                        if let Some(app_exit_events) = app.world().get_resource::<Events<AppExit>>()
-                        {
-                            if let Some(exit) = app_exit_event_reader.read(app_exit_events).last() {
-                                return Err(exit.clone());
-                            }
-                        }
+                        if let Some(exit) = app.should_exit_manual(&mut app_exit_event_reader) {
+                            return Err(exit);
+                        };
 
                         let end_time = Instant::now();
 

crates/bevy_render/src/pipelined_rendering.rs

@@ -193,7 +193,7 @@ fn renderer_extract(app_world: &mut World, _world: &mut World) {
                 render_channels.send_blocking(render_app);
             } else {
                 // Renderer thread panicked
-                world.send_event(AppExit::Error);
+                world.send_event(AppExit::error());
             }
         });
     });

crates/bevy_winit/src/lib.rs

@@ -281,6 +281,7 @@ pub fn winit_runner(mut app: App) -> AppExit {
 
     let mut runner_state = WinitAppRunnerState::default();
 
+    // TODO: AppExit is effectively a u8 we could use a AtomicU8 here instead of a mutex.
     let mut exit_status = Arc::new(Mutex::new(AppExit::Success));
     let handle_exit_status = exit_status.clone();
 
@@ -330,7 +331,7 @@ pub fn winit_runner(mut app: App) -> AppExit {
     // should drop the event handler. if this is not the case something funky is happening.
     Arc::get_mut(&mut exit_status)
         .map(|mutex| mutex.get_mut().unwrap().clone())
-        .unwrap_or(AppExit::Error)
+        .unwrap_or(AppExit::error())
 }
 
 #[allow(clippy::too_many_arguments /* TODO: probs can reduce # of args */)]
@@ -365,11 +366,12 @@ fn handle_winit_event(
         }
         runner_state.redraw_requested = true;
 
+        // BEFORE_MERGE(Brezak): Consider replacing after discussion and before pr.
         if let Some(app_exit_events) = app.world().get_resource::<Events<AppExit>>() {
             let mut exit_events = app_exit_event_reader.read(app_exit_events);
             if exit_events.len() != 0 {
                 *exit_status = exit_events
-                    .find(|exit| **exit == AppExit::Error)
+                    .find(|exit| exit.is_error())
                     .cloned()
                     .unwrap_or(AppExit::Success);
                 event_loop.exit();
@@ -820,11 +822,12 @@ fn run_app_update_if_should(
             }
         }
 
+        // BEFORE_MERGE(Brezak): Consider replacing after discussion and before pr.
         if let Some(app_exit_events) = app.world().get_resource::<Events<AppExit>>() {
             let mut exit_events = app_exit_event_reader.read(app_exit_events);
             if exit_events.len() != 0 {
                 *exit_status = exit_events
-                    .find(|exit| **exit == AppExit::Error)
+                    .find(|exit| exit.is_error())
                     .cloned()
                     .unwrap_or(AppExit::Success);
                 event_loop.exit();