Skip to main content

ifc_model/mutation/
preview.rs

1//! Preview: run a change, look at it, and put the model back exactly.
2//!
3//! A preview records the change like [`Inverse::record`](crate::Inverse::record)
4//! does, then applies the recorded steps backwards instead of returning them.
5//! Entities, file order, type-bucket order, attribute counts, header, id
6//! allocation and diagnostics are put back, the maintained indexes follow
7//! through the same steps, and so does the revision.
8//!
9//! ## Why restoring the revision is sound
10//!
11//! Revisions are process-unique (ADR 0022): each names one state of one model
12//! lineage. The preview puts back exactly the state revision `R` named, so
13//! `R` names exactly one state again. The revisions drawn inside the change
14//! are never reissued (the process-wide counter is not touched), so a cache
15//! keyed by one of them can only miss, never hit a different state. An
16//! `Inverse`, `Transaction` or `History` made before the preview targets `R`
17//! and stays valid; one made inside the change after a write targets a
18//! revision nothing has any more and is refused as stale.
19//!
20//! The rollback never records: the enclosing recording, if any, gains no
21//! steps, because the writes and their undoing cancel.
22
23use std::panic::{catch_unwind, resume_unwind, AssertUnwindSafe};
24
25use crate::model::Model;
26
27impl Model {
28    /// Run `change` on this model, return its result, and put the model back
29    /// exactly as it was, revision included.
30    ///
31    /// Use it to look at a change without making it, for example to mesh what
32    /// a pointer move would create. Unlike [`Inverse::apply`](crate::Inverse::apply),
33    /// which is a new change and draws a new revision, a preview leaves no
34    /// trace: a [`History`](crate::History), [`Transaction`](crate::Transaction)
35    /// or [`Inverse`](crate::Inverse) made before it stays valid.
36    ///
37    /// The cost is what the change writes, not the size of the model. Put
38    /// back are the entities and their order, the type buckets, the header,
39    /// the id allocator, the diagnostics, the maintained indexes and the
40    /// revision. The revisions drawn inside the change are never handed out
41    /// again, and the ids it created are free again. Effects outside the
42    /// model are not rolled back, and a `Transaction` or `Inverse` made
43    /// inside the change after a write is stale afterwards.
44    ///
45    /// Previews nest, and may run inside [`Inverse::record`](crate::Inverse::record)
46    /// or `History::track`, whose recording keeps none of it.
47    ///
48    /// # Panics
49    ///
50    /// If `change` panics the model is rolled back and the revision restored
51    /// before the panic resumes. Panics if `change` ended or replaced the
52    /// recording the preview began (the model is then left as `change` left
53    /// it). If a rollback step itself panics (only through a broken
54    /// [`EntitySource`](crate::EntitySource)) the original payload is lost
55    /// and the model is left partly rolled back.
56    ///
57    /// # Examples
58    ///
59    /// ```
60    /// use ifc_model::{Entity, History, Model};
61    ///
62    /// let mut model = Model::new();
63    /// let mut history = History::new(8);
64    /// history.track(&mut model, |m| {
65    ///     m.push(Entity::new("IFCWALL", Vec::new()));
66    /// });
67    /// history.undo(&mut model).unwrap();
68    /// let revision = model.revision();
69    ///
70    /// let seen = model.preview(|m| {
71    ///     m.push(Entity::new("IFCWALL", Vec::new()));
72    ///     m.len()
73    /// });
74    /// assert_eq!(seen, 1);
75    /// assert!(model.is_empty());
76    /// assert_eq!(model.revision(), revision);
77    /// assert!(history.redo(&mut model).is_ok());
78    /// ```
79    pub fn preview<R>(&mut self, change: impl FnOnce(&mut Model) -> R) -> R {
80        let depth = self.recording_depth();
81        let revision = self.revision();
82        let diagnostics = self.diagnostics().len();
83        self.begin_recording();
84        let outcome = catch_unwind(AssertUnwindSafe(|| change(self)));
85        self.unwind_recording(depth + 1);
86        assert!(
87            self.recording_depth() == depth + 1
88                && self
89                    .recording_mut()
90                    .last()
91                    .is_some_and(|segment| segment.revision == revision),
92            "the change ended a recording it did not begin"
93        );
94        let segment = self.recording_mut().pop().expect("checked above");
95        // Not merged into an enclosing recording: the writes and their
96        // rollback cancel.
97        for step in segment.steps.into_iter().rev() {
98            let _ = step.apply(self);
99        }
100        self.set_max_id(segment.max_id);
101        self.restore_revision(segment.revision);
102        self.truncate_diagnostics(diagnostics);
103        match outcome {
104            Ok(value) => value,
105            Err(panic) => resume_unwind(panic),
106        }
107    }
108}