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
138
139
140
141
142
143

//! Ordered ownership release and fail-stop teardown transactions.

use tracing::error;

use super::recovery::{GenerationRelease, RuntimeGenerations};
use super::state::{RuntimeGeneration, UiState, WindowState};
use crate::RunError;

pub(super) struct RuntimeOwnership {
    pub(super) window: WindowState,
    pub(super) ui: UiState,
    pub(super) generations: RuntimeGenerations<RuntimeGeneration>,
}

pub(super) trait RuntimeOwnershipLifecycle: Sized {
    fn release_renderer(&mut self) -> Result<(), RunError>;
    fn release_platform(&mut self) -> Result<(), RunError>;
    fn teardown_after_backend_release(self);
}

pub(super) struct OrderedRuntimeOwner<T: RuntimeOwnershipLifecycle> {
    ownership: Option<T>,
}

/// Quarantines the ownership graph unless every Context-bound backend release reaches its commit
/// point.
struct BackendReleaseTransaction<T> {
    ownership: Option<T>,
}

impl<T> BackendReleaseTransaction<T> {
    fn new(ownership: T) -> Self {
        Self {
            ownership: Some(ownership),
        }
    }

    fn ownership_mut(&mut self) -> &mut T {
        self.ownership
            .as_mut()
            .expect("renderer release transaction owns the runtime graph")
    }

    fn commit(mut self) -> T {
        self.ownership
            .take()
            .expect("renderer release transaction can commit only once")
    }
}

impl<T> Drop for BackendReleaseTransaction<T> {
    fn drop(&mut self) {
        if let Some(ownership) = self.ownership.take() {
            std::mem::forget(ownership);
        }
    }
}

impl<T: RuntimeOwnershipLifecycle> OrderedRuntimeOwner<T> {
    pub(super) fn new(ownership: T) -> Self {
        Self {
            ownership: Some(ownership),
        }
    }

    pub(super) fn get(&self) -> &T {
        self.ownership
            .as_ref()
            .expect("runtime ownership is available until teardown starts")
    }

    pub(super) fn get_mut(&mut self) -> &mut T {
        self.ownership
            .as_mut()
            .expect("runtime ownership is available until teardown starts")
    }

    pub(super) fn teardown(mut self) -> Result<(), RunError> {
        let ownership = self
            .ownership
            .take()
            .expect("runtime ownership can be consumed only once");
        release_then_teardown_or_quarantine(ownership)
    }
}

impl<T: RuntimeOwnershipLifecycle> Drop for OrderedRuntimeOwner<T> {
    fn drop(&mut self) {
        let Some(ownership) = self.ownership.take() else {
            return;
        };
        if let Err(error) = release_then_teardown_or_quarantine(ownership) {
            error!("Dear App quarantined runtime ownership after backend release failed: {error}");
        }
    }
}

fn release_then_teardown_or_quarantine<T: RuntimeOwnershipLifecycle>(
    ownership: T,
) -> Result<(), RunError> {
    let mut transaction = BackendReleaseTransaction::new(ownership);
    // The transaction quarantines the complete graph if renderer resources still borrow the
    // Context, window, or GPU generation.
    transaction.ownership_mut().release_renderer()?;
    // A platform ownership conflict leaves Context attachment state uncertain. Context drop must
    // not run its fallback teardown after an explicit release failure.
    transaction.ownership_mut().release_platform()?;
    let ownership = transaction.commit();
    ownership.teardown_after_backend_release();
    Ok(())
}

impl RuntimeOwnershipLifecycle for RuntimeOwnership {
    fn release_renderer(&mut self) -> Result<(), RunError> {
        let mut release = RuntimeRelease { ui: &mut self.ui };
        self.generations.shutdown(&mut release)
    }

    fn release_platform(&mut self) -> Result<(), RunError> {
        self.ui.release_platform()
    }

    fn teardown_after_backend_release(self) {
        let Self {
            window,
            ui,
            generations,
        } = self;
        drop(generations);
        ui.teardown_after_platform_release();
        drop(window);
    }
}

struct RuntimeRelease<'a> {
    ui: &'a mut UiState,
}

impl GenerationRelease<RuntimeGeneration> for RuntimeRelease<'_> {
    fn release_generation(&mut self, generation: &mut RuntimeGeneration) -> Result<(), RunError> {
        generation.gpu.release_renderer(&mut self.ui.context)
    }
}