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}