Skip to main content

dive_core/
opts.rs

1//! Strategy switches for ablation.
2//!
3//! Every switch turns one strategy off (`-name`) or on (`+name`) and must
4//! leave every observable result unchanged. They are parsed from a list
5//! such as `-fold,-delta-hash` (`DIVE_CORE_OPT`).
6
7/// Which strategies are on. The default has all of them on.
8#[derive(Clone, Copy, Debug, PartialEq, Eq)]
9#[allow(
10    clippy::struct_excessive_bools,
11    reason = "one independent switch per strategy"
12)]
13pub struct Opts {
14    /// Incremental state and `EXCEPT` hashes from cached node
15    /// hashes. Off (`-delta-hash`): every successor's key is recomputed from
16    /// the leaves of every variable, and `EXCEPT` re-sums every entry.
17    pub delta_hash: bool,
18    /// Probe the seen set before materializing. Off (`-early-probe`):
19    /// every successor is interned first.
20    pub early_probe: bool,
21    /// Hash-consing and equality by handle. Off (`-hashcons`).
22    pub hashcons: bool,
23    /// Symbolic membership in `a..b`, `[D -> R]`, `SUBSET S`, record
24    /// sets and `Seq(S)`. Off (`-symbolic-member`): the set is materialized
25    /// (up to 2^24 elements; beyond that the run is refused).
26    pub symbolic_member: bool,
27    /// Bounded hash indexes for repeated default normalized membership.
28    /// Off (`-member-index`); TLC comparisons always use the original search.
29    pub member_index: bool,
30    /// Keyed result caches. Off (`-memo`).
31    pub memo: bool,
32    /// Keyed result caches for the cached bodies of step predicates
33    /// (implied actions, action constraints), keyed on the primed and
34    /// unprimed variables they read. Off (`-step-memo`).
35    pub step_memo: bool,
36    /// Keyed result caches for zero-arity definitions that a
37    /// next-state action reads primed, keyed on the primed and unprimed
38    /// variables they read, used only once those primed variables are
39    /// assigned. Off (`-primed-memo`).
40    pub primed_memo: bool,
41    /// Parent-delta skip of invariant and constraint conjuncts. Off
42    /// (`-parent-skip`).
43    pub parent_skip: bool,
44    /// The pooled arena. Off (`-arena`): one heap allocation per
45    /// transient value.
46    pub arena: bool,
47    /// Arguments substituted or evaluated eagerly where the demand-order
48    /// rule allows. Off (`-eager`): every argument is a thunk.
49    pub eager: bool,
50    /// Constant folding of closed constant-level subexpressions. Off
51    /// (`-fold`).
52    pub fold: bool,
53    /// The byte cap of each worker's memo tables (not a switch; the engine
54    /// derives it from the run's memory budget).
55    pub memo_cap: usize,
56}
57
58impl Default for Opts {
59    fn default() -> Self {
60        Self {
61            delta_hash: true,
62            early_probe: true,
63            hashcons: true,
64            symbolic_member: true,
65            member_index: true,
66            memo: true,
67            step_memo: true,
68            primed_memo: true,
69            parent_skip: true,
70            arena: true,
71            eager: true,
72            fold: true,
73            memo_cap: crate::memo::DEFAULT_CAP,
74        }
75    }
76}
77
78/// Every switch name, as `DIVE_CORE_OPT` spells it.
79pub const SWITCHES: &[&str] = &[
80    "delta-hash",
81    "early-probe",
82    "hashcons",
83    "symbolic-member",
84    "member-index",
85    "memo",
86    "step-memo",
87    "primed-memo",
88    "parent-skip",
89    "arena",
90    "eager",
91    "fold",
92];
93
94impl Opts {
95    /// Parses a comma-separated list of `-name` (off) and `+name` (on).
96    ///
97    /// ```
98    /// let o = dive_core::Opts::parse("-memo,+delta-hash").unwrap();
99    /// assert!(!o.memo && o.delta_hash && o.arena);
100    /// assert!(dive_core::Opts::default().memo);
101    /// assert!(dive_core::Opts::parse("-inline-subst").is_err());
102    /// ```
103    ///
104    /// # Errors
105    /// An unknown switch. `-inline-subst` is reported as not applicable:
106    /// the core binds substitutions dynamically, never by inlining.
107    pub fn parse(text: &str) -> Result<Self, String> {
108        let mut o = Self::default();
109        for item in text.split(',').map(str::trim).filter(|s| !s.is_empty()) {
110            let (on, name) = match item.as_bytes().first() {
111                Some(b'-') => (false, &item[1..]),
112                Some(b'+') => (true, &item[1..]),
113                _ => (false, item),
114            };
115            let flag = match name {
116                "delta-hash" => &mut o.delta_hash,
117                "early-probe" => &mut o.early_probe,
118                "hashcons" => &mut o.hashcons,
119                "symbolic-member" => &mut o.symbolic_member,
120                "member-index" => &mut o.member_index,
121                "memo" => &mut o.memo,
122                "step-memo" => &mut o.step_memo,
123                "primed-memo" => &mut o.primed_memo,
124                "parent-skip" => &mut o.parent_skip,
125                "arena" => &mut o.arena,
126                "eager" => &mut o.eager,
127                "fold" => &mut o.fold,
128                "inline-subst" => {
129                    return Err(
130                        "`inline-subst` does not apply: the core binds INSTANCE substitutions dynamically (`04-plan-compiler.md` ยง3)".into(),
131                    );
132                }
133                other => {
134                    return Err(format!(
135                        "unknown core switch `{other}` (known: {})",
136                        SWITCHES.join(", ")
137                    ));
138                }
139            };
140            *flag = on;
141        }
142        Ok(o)
143    }
144
145    /// The switches that differ from the default, as `-name` (off) and
146    /// `+name` (on) items, or `default`.
147    #[must_use]
148    pub fn describe(&self) -> String {
149        let flags = [
150            ("delta-hash", self.delta_hash),
151            ("early-probe", self.early_probe),
152            ("hashcons", self.hashcons),
153            ("symbolic-member", self.symbolic_member),
154            ("member-index", self.member_index),
155            ("memo", self.memo),
156            ("step-memo", self.step_memo),
157            ("primed-memo", self.primed_memo),
158            ("parent-skip", self.parent_skip),
159            ("arena", self.arena),
160            ("eager", self.eager),
161            ("fold", self.fold),
162        ];
163        let d = Self::default();
164        let defaults = [
165            d.delta_hash,
166            d.early_probe,
167            d.hashcons,
168            d.symbolic_member,
169            d.member_index,
170            d.memo,
171            d.step_memo,
172            d.primed_memo,
173            d.parent_skip,
174            d.arena,
175            d.eager,
176            d.fold,
177        ];
178        let changed: Vec<String> = flags
179            .iter()
180            .zip(defaults)
181            .filter(|((_, on), def)| on != def)
182            .map(|((n, on), _)| format!("{}{n}", if *on { '+' } else { '-' }))
183            .collect();
184        if changed.is_empty() {
185            "default".into()
186        } else {
187            changed.join(",")
188        }
189    }
190}