winit/platform/
run_on_demand.rs

Help
1use crate::application::ApplicationHandler;
2use crate::error::EventLoopError;
3use crate::event_loop::EventLoop;
4#[cfg(doc)]
5use crate::{
6    event_loop::ActiveEventLoop, platform::pump_events::EventLoopExtPumpEvents, window::Window,
7};
8
9/// Additional methods on [`EventLoop`] to return control flow to the caller.
10pub trait EventLoopExtRunOnDemand {
11    /// Run the application with the event loop on the calling thread.
12    ///
13    /// Unlike [`EventLoop::run_app`], this function accepts non-`'static` (i.e. non-`move`)
14    /// closures and it is possible to return control back to the caller without
15    /// consuming the `EventLoop` (by using [`exit()`]) and
16    /// so the event loop can be re-run after it has exit.
17    ///
18    /// It's expected that each run of the loop will be for orthogonal instantiations of your
19    /// Winit application, but internally each instantiation may re-use some common window
20    /// system resources, such as a display server connection.
21    ///
22    /// This API is not designed to run an event loop in bursts that you can exit from and return
23    /// to while maintaining the full state of your application. (If you need something like this
24    /// you can look at the [`EventLoopExtPumpEvents::pump_app_events()`] API)
25    ///
26    /// Each time `run_app_on_demand` is called the startup sequence of `init`, followed by
27    /// `resume` is being preserved.
28    ///
29    /// See the [`set_control_flow()`] docs on how to change the event loop's behavior.
30    ///
31    /// # Caveats
32    /// - This extension isn't available on all platforms, since it's not always possible to return
33    ///   to the caller (specifically this is impossible on iOS and Web - though with the Web
34    ///   backend it is possible to use
35    #[cfg_attr(
36        any(web_platform, docsrs),
37        doc = "  [`EventLoopExtWeb::spawn_app()`][crate::platform::web::EventLoopExtWeb::spawn_app()]"
38    )]
39    #[cfg_attr(not(any(web_platform, docsrs)), doc = "  `EventLoopExtWeb::spawn_app()`")]
40    ///   [^1] more than once instead).
41    /// - No [`Window`] state can be carried between separate runs of the event loop.
42    ///
43    /// You are strongly encouraged to use [`EventLoop::run_app()`] for portability, unless you
44    /// specifically need the ability to re-run a single event loop more than once
45    ///
46    /// # Supported Platforms
47    /// - Windows
48    /// - Linux
49    /// - macOS
50    /// - Android
51    ///
52    /// # Unsupported Platforms
53    /// - **Web:**  This API is fundamentally incompatible with the event-based way in which Web
54    ///   browsers work because it's not possible to have a long-running external loop that would
55    ///   block the browser and there is nothing that can be polled to ask for new events. Events
56    ///   are delivered via callbacks based on an event loop that is internal to the browser itself.
57    /// - **iOS:** It's not possible to stop and start an `UIApplication` repeatedly on iOS.
58    ///
59    /// [^1]: `spawn_app()` is only available on the Web platforms.
60    ///
61    /// [`exit()`]: ActiveEventLoop::exit()
62    /// [`set_control_flow()`]: ActiveEventLoop::set_control_flow()
63    fn run_app_on_demand<A: ApplicationHandler>(&mut self, app: A) -> Result<(), EventLoopError>;
64}
65
66impl EventLoopExtRunOnDemand for EventLoop {
67    fn run_app_on_demand<A: ApplicationHandler>(&mut self, app: A) -> Result<(), EventLoopError> {
68        self.event_loop.run_app_on_demand(app)
69    }
70}
71
72/// ```compile_fail
73/// use winit::event_loop::EventLoop;
74/// use winit::platform::run_on_demand::EventLoopExtRunOnDemand;
75///
76/// let mut event_loop = EventLoop::new().unwrap();
77/// event_loop.run_on_demand(|_, _| {
78///     // Attempt to run the event loop re-entrantly; this must fail.
79///     event_loop.run_on_demand(|_, _| {});
80/// });
81/// ```
82#[allow(dead_code)]
83fn test_run_on_demand_cannot_access_event_loop() {}
winit/platform/run_on_demand.rs

winit/platform/
run_on_demand.rs
