From f0c504947ce653068a424979faf226c1e990818d Mon Sep 17 00:00:00 2001 From: Stephen Martindale Date: Wed, 18 Jan 2023 23:02:38 +0000 Subject: [PATCH] Docs: App::run() might never return; effect of WinitSettings::return_from_run. (#7228) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # Objective See: - https://github.com/bevyengine/bevy/issues/7067#issuecomment-1381982285 - (This does not fully close that issue in my opinion.) - https://discord.com/channels/691052431525675048/1063454009769340989 ## Solution This merge request adds documentation: 1. Alert users to the fact that `App::run()` might never return and code placed after it might never be executed. 2. Makes `winit::WinitSettings::return_from_run` discoverable. 3. Better explains why `winit::WinitSettings::return_from_run` is discouraged and better links to up-stream docs. on that topic. 4. Adds notes to the `app/return_after_run.rs` example which otherwise promotes a feature that carries caveats. Furthermore, w.r.t `winit::WinitSettings::return_from_run`: - Broken links to `winit` docs are fixed. - Links now point to BOTH `EventLoop::run()` and `EventLoopExtRunReturn::run_return()` which are the salient up-stream pages and make more sense, taken together. - Collateral damage: "Supported platforms" heading; disambiguation of "run" → `App::run()`; links. ## Future Work I deliberately structured the "`run()` might not return" section under `App::run()` to allow for alternative patterns (e.g. `AppExit` event, `WindowClosed` event) to be listed or mentioned, beneath it, in the future. --- crates/bevy_app/src/app.rs | 18 +++++++++++++++++ crates/bevy_winit/src/winit_config.rs | 29 +++++++++++++++++++-------- examples/app/return_after_run.rs | 11 ++++++++++ 3 files changed, 50 insertions(+), 8 deletions(-) diff --git a/crates/bevy_app/src/app.rs b/crates/bevy_app/src/app.rs index 2a47aabb964c0..a8db6bfc042f1 100644 --- a/crates/bevy_app/src/app.rs +++ b/crates/bevy_app/src/app.rs @@ -178,6 +178,24 @@ impl App { /// Finalizes the [`App`] configuration. For general usage, see the example on the item /// level documentation. /// + /// # `run()` might not return + /// + /// Calls to [`App::run()`] might never return. + /// + /// In simple and *headless* applications, one can expect that execution will + /// proceed, normally, after calling [`run()`](App::run()) but this is not the case for + /// windowed applications. + /// + /// Windowed apps are typically driven by an *event loop* or *message loop* and + /// some window-manager APIs expect programs to terminate when their primary + /// window is closed and that event loop terminates – behaviour of processes that + /// do not is often platform dependent or undocumented. + /// + /// By default, *Bevy* uses the `winit` crate for window creation. See + /// [`WinitSettings::return_from_run`](https://docs.rs/bevy/latest/bevy/winit/struct.WinitSettings.html#structfield.return_from_run) + /// for further discussion of this topic and for a mechanism to require that [`App::run()`] + /// *does* return – albeit one that carries its own caveats and disclaimers. + /// /// # Panics /// /// Panics if called from `Plugin::build()`, because it would prevent other plugins to properly build. diff --git a/crates/bevy_winit/src/winit_config.rs b/crates/bevy_winit/src/winit_config.rs index c1db2b2fd27e6..40bfd1f87323b 100644 --- a/crates/bevy_winit/src/winit_config.rs +++ b/crates/bevy_winit/src/winit_config.rs @@ -4,15 +4,28 @@ use bevy_utils::Duration; /// A resource for configuring usage of the `rust_winit` library. #[derive(Debug, Resource)] pub struct WinitSettings { - /// Configures the winit library to return control to the main thread after the - /// [run](bevy_app::App::run) loop is exited. Winit strongly recommends avoiding this when - /// possible. Before using this please read and understand the - /// [caveats](winit::platform::run_return::EventLoopExtRunReturn::run_return) in the winit - /// documentation. + /// Configures `winit` to return control to the caller after exiting the + /// event loop, enabling [`App::run()`](bevy_app::App::run()) to return. /// - /// This feature is only available on desktop `target_os` configurations. Namely `windows`, - /// `macos`, `linux`, `dragonfly`, `freebsd`, `netbsd`, and `openbsd`. If set to true on an - /// unsupported platform [run](bevy_app::App::run) will panic. + /// By default, [`return_from_run`](Self::return_from_run) is `false` and *Bevy* + /// will use `winit`'s + /// [`EventLoop::run()`](https://docs.rs/winit/latest/winit/event_loop/struct.EventLoop.html#method.run) + /// to initiate the event loop. + /// [`EventLoop::run()`](https://docs.rs/winit/latest/winit/event_loop/struct.EventLoop.html#method.run) + /// will never return but will terminate the process after the event loop exits. + /// + /// Setting [`return_from_run`](Self::return_from_run) to `true` will cause *Bevy* + /// to use `winit`'s + /// [`EventLoopExtRunReturn::run_return()`](https://docs.rs/winit/latest/winit/platform/run_return/trait.EventLoopExtRunReturn.html#tymethod.run_return) + /// instead which is strongly discouraged by the `winit` authors. + /// + /// # Supported platforms + /// + /// This feature is only available on the following desktop `target_os` configurations: + /// `windows`, `macos`, `linux`, `dragonfly`, `freebsd`, `netbsd`, and `openbsd`. + /// + /// Setting [`return_from_run`](Self::return_from_run) to `true` on + /// unsupported platforms will cause [`App::run()`](bevy_app::App::run()) to panic! pub return_from_run: bool, /// Configures how the winit event loop updates while the window is focused. pub focused_mode: UpdateMode, diff --git a/examples/app/return_after_run.rs b/examples/app/return_after_run.rs index 966659688655e..f1fc07b50c5c3 100644 --- a/examples/app/return_after_run.rs +++ b/examples/app/return_after_run.rs @@ -1,4 +1,15 @@ //! Shows how to return to the calling function after a windowed Bevy app has exited. +//! +//! In windowed *Bevy* applications, executing code below a call to `App::run()` is +//! not recommended because `App::run()` might never return. +//! +//! This example demonstrates the use of `WinitSettings::return_from_run` to +//! require that `App::run()` *does* return but this is not recommended. Be sure +//! to read the documentation on both `App::run()` and `WinitSettings::return_from_run` +//! for caveats and further details: +//! +//! - +//! - use bevy::{prelude::*, winit::WinitSettings};