dear-app 0.16.0-alpha.2

Generation-aware Dear ImGui application runtime for dear-imgui-rs on Winit and WGPU
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

//! Runtime initialization rollback and exactly-once shutdown coordination.

use super::state::{UiState, WindowState};
use crate::{Application, ApplicationStage, RunError, ShutdownContext};

pub(super) fn abort_runtime_initialization<A: Application>(
    application: &mut A,
    mut ui: UiState,
    window: WindowState,
    primary_error: RunError,
) -> RunError {
    super::state::preserve_initialization_error(primary_error, move || {
        let application_result = {
            let mut shutdown = ShutdownContext {
                imgui: &mut ui.context,
                window: &window.window,
                generation: None,
            };
            application
                .shutdown(&mut shutdown)
                .map_err(|error| error.during_application_stage(ApplicationStage::Shutdown))
        };
        let platform_result = ui.release_platform_then_teardown_or_quarantine();
        drop(window);
        application_result.and(platform_result)
    })
}

#[derive(Default)]
pub(super) struct RuntimeShutdownErrors {
    pub(super) terminal_error: Option<RunError>,
    pub(super) shutdown_error: Option<RunError>,
}

pub(super) fn finish_runtime_shutdown(
    terminal_error: Option<RunError>,
    application_shutdown: impl FnOnce() -> Option<RunError>,
    release_backends: impl FnOnce() -> Result<(), RunError>,
) -> RuntimeShutdownErrors {
    // User-owned resources may still need the Context, but renderer and platform teardown must
    // proceed even when the hook reports an error. Backend release owns the Context fail-stop
    // decision and quarantines the complete graph if it cannot commit. The application hook runs
    // first, so its error remains the shutdown primary if backend release also fails.
    let application_error = application_shutdown();
    let release_error = release_backends().err();
    if let (Some(primary), Some(secondary)) = (&application_error, &release_error) {
        tracing::warn!(
            %primary,
            %secondary,
            "Dear App backend release failed after application shutdown had already failed"
        );
    }
    RuntimeShutdownErrors {
        terminal_error,
        shutdown_error: application_error.or(release_error),
    }
}

#[derive(Default)]
pub(super) struct ShutdownCoordinator {
    started: bool,
    terminal_error: Option<RunError>,
    shutdown_error: Option<RunError>,
}

impl ShutdownCoordinator {
    pub(super) const fn started(&self) -> bool {
        self.started
    }

    pub(super) fn remember_error(&mut self, error: RunError) {
        if self.terminal_error.is_none() {
            self.terminal_error = Some(error);
        }
    }

    pub(super) fn shutdown_once<R, A>(
        &mut self,
        runtime: &mut Option<R>,
        application: &mut A,
        shutdown: impl FnOnce(R, &mut A) -> RuntimeShutdownErrors,
    ) {
        if self.started {
            return;
        }
        self.started = true;
        let errors = runtime
            .take()
            .map(|runtime| shutdown(runtime, application))
            .unwrap_or_default();
        if let Some(error) = errors.terminal_error {
            self.remember_error(error);
        }
        if self.shutdown_error.is_none() {
            self.shutdown_error = errors.shutdown_error;
        }
    }

    pub(super) fn take_terminal_error(&mut self) -> Option<RunError> {
        self.terminal_error.take()
    }

    pub(super) fn take_shutdown_error(&mut self) -> Option<RunError> {
        self.shutdown_error.take()
    }
}

pub(super) fn resolve_run_result(
    terminal_before_shutdown: Option<RunError>,
    event_loop_result: Result<(), winit::error::EventLoopError>,
    shutdown_error: Option<RunError>,
) -> Result<(), RunError> {
    if let Some(error) = terminal_before_shutdown {
        if let Some(secondary) = &shutdown_error {
            tracing::warn!(
                primary = %error,
                %secondary,
                "Dear App shutdown failed after an earlier runtime failure"
            );
        }
        return Err(error);
    }
    if let Err(error) = event_loop_result {
        if let Some(secondary) = &shutdown_error {
            tracing::warn!(
                primary = %error,
                %secondary,
                "Dear App shutdown failed after an event-loop failure"
            );
        }
        return Err(error.into());
    }
    match shutdown_error {
        Some(error) => Err(error),
        None => Ok(()),
    }
}