salsa 0.27.1

A generic framework for on-demand, incrementalized computation (experimental)
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

use crate::Backtrace;
use crate::DatabaseKeyIndex;
use crate::function::memo::{Memo, MemoHeader};
use crate::function::{Configuration, IngredientImpl};
use crate::zalsa_local::QueryRevisions;
use std::fmt;

impl<C> IngredientImpl<C>
where
    C: Configuration,
{
    /// If the value/durability of this memo is equal to what is found in `revisions`/`value`,
    /// then update `revisions.changed_at` to match `self.revisions.changed_at`. This is invoked
    /// on an old memo when a new memo has been produced to check whether there have been changed.
    pub(super) fn backdate_if_appropriate<'db>(
        &self,
        old_memo: &Memo<'db, C>,
        index: DatabaseKeyIndex,
        revisions: &mut QueryRevisions,
        value: &C::Output<'db>,
    ) {
        if old_memo.header.can_backdate(revisions)
            && old_memo
                .value
                .as_ref()
                .is_some_and(|old_value| C::values_equal(old_value, value))
        {
            old_memo.header.backdate(index, revisions);
        }
    }
}

impl MemoHeader {
    fn can_backdate(&self, revisions: &QueryRevisions) -> bool {
        // We've seen issues where queries weren't re-validated when backdating provisional values
        // in ty. This is more of a bandaid because we're close to a release and don't have the time to prove
        // right now whether backdating could be made safe for queries participating in queries.
        // TODO: Write a test that demonstrates that backdating queries participating in a cycle isn't safe
        // OR write many tests showing that it is (and fixing the case where it didn't correctly account for today).
        revisions.cycle_heads().is_empty()
            && !self.may_be_provisional()
            // Careful: if the value became less durable than it
            // used to be, that is a "breaking change" that our
            // consumers must be aware of. Becoming *more* durable
            // is not. See the test `durable_to_less_durable`.
            && revisions.durability >= self.revisions.durability
    }

    fn backdate(&self, index: DatabaseKeyIndex, revisions: &mut QueryRevisions) {
        crate::tracing::debug!(
            "{index:?} value is equal, back-dating to {:?}",
            self.revisions.changed_at,
        );

        if self.revisions.changed_at > revisions.changed_at {
            report_backdate_violation(index, self.revisions.changed_at, revisions.changed_at);
        }

        revisions.changed_at = self.revisions.changed_at;
    }
}

#[cold]
#[inline(never)]
fn report_backdate_violation(
    index: DatabaseKeyIndex,
    old_changed_at: crate::Revision,
    new_changed_at: crate::Revision,
) {
    if cfg!(debug_assertions) {
        let message = BackdateViolation {
            index,
            old_changed_at,
            new_changed_at,
            backtrace: None,
        };
        panic!("{message}");
    } else {
        let message = BackdateViolation {
            index,
            old_changed_at,
            new_changed_at,
            backtrace: Backtrace::capture(),
        };
        crate::tracing::warn!("{message}");
    }
}

struct BackdateViolation {
    index: DatabaseKeyIndex,
    old_changed_at: crate::Revision,
    new_changed_at: crate::Revision,
    backtrace: Option<Backtrace>,
}

impl fmt::Display for BackdateViolation {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "query {:?} returned the same value, but the previous execution changed at {:?} and \
             the new execution changed at {:?}. This usually means the query re-executed because \
             an input changed, but then branched on untracked state (for example, a global \
             variable, a non-salsa field on the database, or filesystem state read outside salsa) \
             and no longer read that input. This is usually a bug in the query implementation. \
             Queries that branch on untracked state can also produce stale results. If the query \
             has no untracked reads, please open a Salsa issue.",
            self.index, self.old_changed_at, self.new_changed_at,
        )?;

        if let Some(backtrace) = &self.backtrace {
            write!(f, "\n{backtrace}")?;
        }

        Ok(())
    }
}