ifc_model/mutation/record.rs
1//! Recording: capture the exact inverse of a run of model writes.
2//!
3//! While a recording is open, every primitive write (`insert`, `push`,
4//! `set_attribute`, `set_attributes`, `truncate_attributes`, `retype`, `remove`,
5//! `header_mut`,
6//! `reserve_ids_through`) keeps the step that undoes it. Ending the recording
7//! yields an [`Inverse`].
8//!
9//! Recordings nest. The inner recording's inverse is returned to its caller
10//! and its steps also join the enclosing recording, so the outer inverse
11//! undoes everything the inner one did and more.
12//!
13//! Outside a recording nothing is captured and a write pays one emptiness
14//! check.
15
16use crate::model::Model;
17use crate::mutation::inverse::Inverse;
18use crate::mutation::step::Step;
19
20/// The writes of one open recording.
21#[derive(Debug, Clone)]
22pub(crate) struct Segment {
23 /// Undoing steps in the order the writes happened.
24 pub(crate) steps: Vec<Step>,
25 /// `max_id` when the recording began.
26 pub(crate) max_id: u64,
27 /// The revision when the recording began.
28 pub(crate) revision: u64,
29}
30
31/// The open recordings of a model. A clone is not recording: its writes are
32/// not the original's to capture.
33#[derive(Debug, Default)]
34pub(crate) struct Recording(pub(crate) Vec<Segment>);
35
36impl Clone for Recording {
37 fn clone(&self) -> Self {
38 Self::default()
39 }
40}
41
42impl Model {
43 /// Start capturing the inverse of every write that follows.
44 ///
45 /// Nestable: each call needs its own [`Model::end_recording`].
46 pub fn begin_recording(&mut self) {
47 let segment = Segment {
48 steps: Vec::new(),
49 max_id: self.max_id(),
50 revision: self.revision(),
51 };
52 self.recording_mut().push(segment);
53 }
54
55 /// Stop the innermost recording and return the inverse of its writes,
56 /// or `None` when no recording is open.
57 ///
58 /// The inner steps are also kept by the enclosing recording, if any.
59 pub fn end_recording(&mut self) -> Option<Inverse> {
60 let segment = self.recording_mut().pop()?;
61 if let Some(outer) = self.recording_mut().last_mut() {
62 outer.steps.extend(segment.steps.iter().cloned());
63 }
64 let mut steps = segment.steps;
65 steps.reverse();
66 Some(Inverse::new(
67 steps,
68 segment.max_id,
69 segment.revision,
70 self.revision(),
71 ))
72 }
73
74 /// How many recordings are open.
75 pub(crate) fn recording_depth(&self) -> usize {
76 self.recording_len()
77 }
78
79 /// Ends recordings opened inside a change that did not end them, down to
80 /// `depth`, keeping their steps in the one below.
81 pub(crate) fn unwind_recording(&mut self, depth: usize) {
82 while self.recording_len() > depth {
83 let segment = self.recording_mut().pop().expect("depth checked");
84 if let Some(outer) = self.recording_mut().last_mut() {
85 outer.steps.extend(segment.steps);
86 }
87 }
88 }
89
90 /// Whether a recording is open.
91 pub fn is_recording(&self) -> bool {
92 !self.recording_is_empty()
93 }
94}