About salsa
Salsa is a Rust framework for writing incremental, on-demand programs -- these are programs that want to adapt to changes in their inputs, continuously producing a new output that is up-to-date. Salsa is based on the the incremental recompilation techniques that we built for rustc, and many (but not all) of its users are building compilers or other similar tooling.
If you'd like to learn more about Salsa, check out:
- The overview, for a brief summary.
- The tutorial, for a detailed look.
- You can also watch some of our videos, though the content there is rather out of date.
If you'd like to chat about Salsa, or you think you might like to contribute, please jump on to our Zulip instance at salsa.zulipchat.com.
Salsa overview
⚠️ IN-PROGRESS VERSION OF SALSA. ⚠️
This page describes the unreleased "Salsa 2022" version, which is a major departure from older versions of salsa. The code here works but is only available on github and from the
salsa-2022crate.If you are looking for the older version of salsa, simply visit this link
This page contains a brief overview of the pieces of a Salsa program. For a more detailed look, check out the tutorial, which walks through the creation of an entire project end-to-end.
Goal of Salsa
The goal of Salsa is to support efficient incremental recomputation. Salsa is used in rust-analyzer, for example, to help it recompile your program quickly as you type.
The basic idea of a Salsa program is like this:
#![allow(unused)] fn main() { let mut input = ...; loop { let output = your_program(&input); modify(&mut input); } }
You start out with an input that has some value. You invoke your program to get back a result. Some time later, you modify the input and invoke your program again. Our goal is to make this second call faster by re-using some of the results from the first call.
In reality, of course, you can have many inputs and "your program" may be many different methods and functions defined on those inputs. But this picture still conveys a few important concepts:
- Salsa separates out the "incremental computation" (the function
your_program) from some outer loop that is defining the inputs. - Salsa gives you the tools to define
your_program. - Salsa assumes that
your_programis a purely deterministic function of its inputs, or else this whole setup makes no sense. - The mutation of inputs always happens outside of
your_program, as part of this master loop.
Database
Each time you run your program, Salsa remembers the values of each computation in a database. When the inputs change, it consults this database to look for values that can be reused. The database is also used to implement interning (making a canonical version of a value that can be copied around and cheaply compared for equality) and other convenient Salsa features.
Inputs
Every Salsa program begins with an input. Inputs are special structs that define the starting point of your program. Everything else in your program is ultimately a deterministic function of these inputs.
For example, in a compiler, there might be an input defining the contents of a file on disk:
#![allow(unused)] fn main() { #[salsa::input] pub struct ProgramFile { pub path: PathBuf, pub contents: String, } }
You create an input by using the new method.
Because the values of input fields are stored in the database, you also give an &mut-reference to the database:
#![allow(unused)] fn main() { let file: ProgramFile = ProgramFile::new( &mut db, PathBuf::from("some_path.txt"), String::from("fn foo() { }"), ); }
Salsa structs are just integers
The ProgramFile struct generated by the salsa::input macro doesn't actually store any data. It's just a newtyped integer id:
#![allow(unused)] fn main() { // Generated by the `#[salsa::input]` macro: #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct ProgramFile(salsa::Id); }
This means that, when you have a ProgramFile, you can easily copy it around and put it wherever you like.
To actually read any of its fields, however, you will need to use the database and a getter method.
Reading fields and return_ref
You can access the value of an input's fields by using the getter method.
As this is only reading the field, it just needs a &-reference to the database:
#![allow(unused)] fn main() { let contents: String = file.contents(&db); }
Invoking the accessor clones the value from the database.
Sometimes this is not what you want, so you can annotate fields with #[return_ref] to indicate that they should return a reference into the database instead:
#![allow(unused)] fn main() { #[salsa::input] pub struct ProgramFile { pub path: PathBuf, #[return_ref] pub contents: String, } }
Now file.contents(&db) will return an &String.
You can also use the data method to access the entire struct:
#![allow(unused)] fn main() { file.data(&db) }
Writing input fields
Finally, you can also modify the value of an input field by using the setter method.
Since this is modifying the input, the setter takes an &mut-reference to the database:
#![allow(unused)] fn main() { file.set_contents(&mut db, String::from("fn foo() { /* add a comment */ }")); }
Tracked functions
Once you've defined your inputs, the next thing to define are tracked functions:
#![allow(unused)] fn main() { #[salsa::tracked] fn parse_file(db: &dyn crate::Db, file: ProgramFile) -> Ast { let contents: &str = file.contents(db); ... } }
When you call a tracked function, Salsa will track which inputs it accesses (in this example, file.contents(db)).
It will also memoize the return value (the Ast, in this case).
If you call a tracked function twice, Salsa checks if the inputs have changed; if not, it can return the memoized value.
The algorithm Salsa uses to decide when a tracked function needs to be re-executed is called the red-green algorithm, and it's where the name Salsa comes from.
Tracked functions have to follow a particular structure:
- They must take a
&-reference to the database as their first argument.- Note that because this is an
&-reference, it is not possible to create or modify inputs during a tracked function!
- Note that because this is an
- They must take a "Salsa struct" as the second argument -- in our example, this is an input struct, but there are other kinds of Salsa structs we'll describe shortly.
- They can take additional arguments, but it's faster and better if they don't.
Tracked functions can return any clone-able type. A clone is required since, when the value is cached, the result will be cloned out of the database. Tracked functions can also be annotated with #[return_ref] if you would prefer to return a reference into the database instead (if parse_file were so annotated, then callers would actually get back an &Ast, for example).
Tracked structs
Tracked structs are intermediate structs created during your computation. Like inputs, their fields are stored inside the database, and the struct itself just wraps an id. Unlike inputs, they can only be created inside a tracked function, and their fields can never change once they are created. Getter methods are provided to read the fields, but there are no setter methods1. Example:
#![allow(unused)] fn main() { #[salsa::tracked] struct Ast { #[return_ref] top_level_items: Vec<Item>, } }
Just as with an input, new values are created by invoking Ast::new.
Unlike with an input, the new for a tracked struct only requires a &-reference to the database:
#![allow(unused)] fn main() { #[salsa::tracked] fn parse_file(db: &dyn crate::Db, file: ProgramFile) -> Ast { let contents: &str = file.contents(db); let parser = Parser::new(contents); let mut top_level_items = vec![]; while let Some(item) = parser.parse_top_level_item() { top_level_items.push(item); } Ast::new(db, top_level_items) // <-- create an Ast! } }
#[id] fields
When a tracked function is re-executed because its inputs have changed, the tracked structs it creates in the new execution are matched against those from the old execution, and the values of their fields are compared. If the field values have not changed, then other tracked functions that only read those fields will not be re-executed.
Normally, tracked structs are matched up by the order in which they are created.
For example, the first Ast that is created by parse_file in the old execution will be matched against the first Ast created by parse_file in the new execution.
In our example, parse_file only ever creates a single Ast, so this works great.
Sometimes, however, it doesn't work so well.
For example, imagine that we had a tracked struct for items in the file:
#![allow(unused)] fn main() { #[salsa::tracked] struct Item { name: Word, // we'll define Word in a second! ... } }
Maybe our parser first creates an Item with the name foo and then later a second Item with the name bar.
Then the user changes the input to reorder the functions.
Although we are still creating the same number of items, we are now creating them in the reverse order, so the naive algorithm will match up the old foo struct with the new bar struct.
This will look to Salsa as though the foo function was renamed to bar and the bar function was renamed to foo.
We'll still get the right result, but we might do more recomputation than we needed to do if we understood that they were just reordered.
To address this, you can tag fields in a tracked struct as #[id]. These fields are then used to "match up" struct instances across executions:
#![allow(unused)] fn main() { #[salsa::tracked] struct Item { #[id] name: Word, // we'll define Word in a second! ... } }
Specify the result of tracked functions for particular structs
Sometimes it is useful to define a tracked function but specify its value for some particular struct specially. For example, maybe the default way to compute the representation for a function is to read the AST, but you also have some built-in functions in your language and you want to hard-code their results. This can also be used to simulate a field that is initialized after the tracked struct is created.
To support this use case, you can use the specify method associated with tracked functions.
To enable this method, you need to add the specify flag to the function to alert users that its value may sometimes be specified externally.
#![allow(unused)] fn main() { #[salsa::tracked(specify)] // <-- specify flag required fn representation(db: &dyn crate::Db, item: Item) -> Representation { // read the user's input AST by default let ast = ast(db, item); // ... } fn create_builtin_item(db: &dyn crate::Db) -> Item { let i = Item::new(db, ...); let r = hardcoded_representation(); representation::specify(db, i, r); // <-- use the method! i } }
Specifying is only possible for tracked functions that take a single tracked struct as an argument (besides the database).
Interned structs
The final kind of Salsa struct are interned structs. Interned structs are useful for quick equality comparison. They are commonly used to represent strings or other primitive values.
Most compilers, for example, will define a type to represent a user identifier:
#![allow(unused)] fn main() { #[salsa::interned] struct Word { #[return_ref] pub text: String, } }
As with input and tracked structs, the Word struct itself is just a newtyped integer, and the actual data is stored in the database.
You can create a new interned struct using new, just like with input and tracked structs:
#![allow(unused)] fn main() { let w1 = Word::new(db, "foo".to_string()); let w2 = Word::new(db, "bar".to_string()); let w3 = Word::new(db, "foo".to_string()); }
When you create two interned structs with the same field values, you are guaranteed to get back the same integer id. So here, we know that assert_eq!(w1, w3) is true and assert_ne!(w1, w2).
You can access the fields of an interned struct using a getter, like word.text(db). These getters respect the #[return_ref] annotation. Like tracked structs, the fields of interned structs are immutable.
Accumulators
The final Salsa concept are accumulators. Accumulators are a way to report errors or other "side channel" information that is separate from the main return value of your function.
To create an accumulator, you declare a type as an accumulator:
#![allow(unused)] fn main() { #[salsa::accumulator] pub struct Diagnostics(String); }
It must be a newtype of something, like String. Now, during a tracked function's execution, you can push those values:
#![allow(unused)] fn main() { Diagnostics::push(db, "some_string".to_string()) }
Then later, from outside the execution, you can ask for the set of diagnostics that were accumulated by some particular tracked function. For example, imagine that we have a type-checker and, during type-checking, it reports some diagnostics:
#![allow(unused)] fn main() { #[salsa::tracked] fn type_check(db: &dyn Db, item: Item) { // ... Diagnostics::push(db, "some error message".to_string()) // ... } }
we can then later invoke the associated accumulated function to get all the String values that were pushed:
#![allow(unused)] fn main() { let v: Vec<String> = type_check::accumulated::<Diagnostics>(db); }
Tutorial: calc
⚠️ IN-PROGRESS VERSION OF SALSA. ⚠️
This page describes the unreleased "Salsa 2022" version, which is a major departure from older versions of salsa. The code here works but is only available on github and from the
salsa-2022crate.If you are looking for the older version of salsa, simply visit this link
This tutorial walks through an end-to-end example of using Salsa. It does not assume you know anything about salsa, but reading the overview first is probably a good idea to get familiar with the basic concepts.
Our goal is define a compiler/interpreter for a simple language called calc.
The calc compiler takes programs like the following and then parses and executes them:
fn area_rectangle(w, h) = w * h
fn area_circle(r) = 3.14 * r * r
print area_rectangle(3, 4)
print area_circle(1)
print 11 * 2
When executed, this program prints 12, 3.14, and 22.
If the program contains errors (e.g., a reference to an undefined function), it prints those out too. And, of course, it will be reactive, so small changes to the input don't require recompiling (or rexecuting, necessarily) the entire thing.
Basic structure
Before we do anything with Salsa, let's talk about the basic structure of the calc compiler. Part of Salsa's design is that you are able to write programs that feel 'pretty close' to what a natural Rust program looks like.
Example program
This is our example calc program:
x = 5
y = 10
z = x + y * 3
print z
Parser
The calc compiler takes as input a program, represented by a string:
#![allow(unused)] fn main() { struct ProgramSource { text: String } }
The first thing it does it to parse that string into a series of statements that look something like the following pseudo-Rust:1
#![allow(unused)] fn main() { enum Statement { /// Defines `fn <name>(<args>) = <body>` Function(Function), /// Defines `print <expr>` Print(Expression), } /// Defines `fn <name>(<args>) = <body>` struct Function { name: FunctionId, args: Vec<VariableId>, body: Expression } }
where an expression is something like this (pseudo-Rust, because the Expression enum is recursive):
#![allow(unused)] fn main() { enum Expression { Op(Expression, Op, Expression), Number(f64), Variable(VariableId), Call(FunctionId, Vec<Expression>), } enum Op { Add, Subtract, Multiply, Divide, } }
Finally, for function/variable names, the FunctionId and VariableId types will be interned strings:
#![allow(unused)] fn main() { type FunctionId = /* interned string */; type VariableId = /* interned string */; }
Because calc is so simple, we don't have to bother separating out the lexer from the parser.
Checker
The "checker" has the job of ensuring that the user only references variables that have been defined.
We're going to write the checker in a "context-less" style,
which is a bit less intuitive but allows for more incremental re-use.
The idea is to compute, for a given expression, which variables it references.
Then there is a function check which ensures that those variables are a subset of those that are already defined.
Interpreter
The interpreter will execute the program and print the result. We don't bother with much incremental re-use here, though it's certainly possible.
Jars and databases
Before we can define the interesting parts of our Salsa program, we have to setup a bit of structure that defines the Salsa database. The database is a struct that ultimately stores all of Salsa's intermediate state, such as the memoized return values from tracked functions.
The database itself is defined in terms of intermediate structures, called jars1, which themselves contain the data for each function. This setup allows Salsa programs to be divided amongst many crates. Typically, you define one jar struct per crate, and then when you construct the final database, you simply list the jar structs. This permits the crates to define private functions and other things that are members of the jar struct, but not known directly to the database.
Jars of salsa -- get it? Get it??2
OK, maybe it also brings to mind Java .jar files, but there's no real relationship. A jar is just a Rust struct, not a packaging format.
Defining a jar struct
To define a jar struct, you create a tuple struct with the #[salsa::jar] annotation:
#![allow(unused)] fn main() { #[salsa::jar(db = Db)] pub struct Jar( crate::compile::compile, crate::ir::SourceProgram, crate::ir::Program, crate::ir::VariableId, crate::ir::FunctionId, crate::ir::Function, crate::ir::Diagnostics, crate::ir::Span, crate::parser::parse_statements, crate::type_check::type_check_program, crate::type_check::type_check_function, crate::type_check::find_function, ); }
Although it's not required, it's highly recommended to put the jar struct at the root of your crate, so that it can be referred to as crate::Jar.
All of the other Salsa annotations reference a jar struct, and they all default to the path crate::Jar.
If you put the jar somewhere else, you will have to override that default.
Defining the database trait
The #[salsa::jar] annotation also includes a db = Db field.
The value of this field (normally Db) is the name of a trait that represents the database.
Salsa programs never refer directly to the database; instead, they take a &dyn Db argument.
This allows for separate compilation, where you have a database that contains the data for two jars, but those jars don't depend on one another.
The database trait for our calc crate is very simple:
#![allow(unused)] fn main() { pub trait Db: salsa::DbWithJar<Jar> {} }
When you define a database trait like Db, the one thing that is required is that it must have a supertrait salsa::DbWithJar<Jar>,
where Jar is the jar struct. If your jar depends on other jars, you can have multiple such supertraits (e.g., salsa::DbWithJar<other_crate::Jar>).
Typically the Db trait has no other members or supertraits, but you are also free to add whatever other things you want in the trait.
When you define your final database, it will implement the trait, and you can then define the implementation of those other things.
This allows you to create a way for your jar to request context or other info from the database that is not moderated through Salsa,
should you need that.
Implementing the database trait for the jar
The Db trait must be implemented by the database struct.
We're going to define the database struct in a later section,
and one option would be to simply implement the jar Db trait there.
However, since we don't define any custom logic in the trait,
a common choice is to write a blanket impl for any type that implements DbWithJar<Jar>,
and that's what we do here:
#![allow(unused)] fn main() { impl<DB> Db for DB where DB: ?Sized + salsa::DbWithJar<Jar> {} }
Summary
If the concept of a jar seems a bit abstract to you, don't overthink it. The TL;DR is that when you create a Salsa program, you need to perform the following steps:
- In each of your crates:
- Define a
#[salsa::jar(db = Db)]struct, typically atcrate::Jar, and list each of your various Salsa-annotated things inside of it. - Define a
Dbtrait, typically atcrate::Db, that you will use in memoized functions and elsewhere to refer to the database struct.
- Define a
- Once, typically in your final crate:
- Define a database
D, as described in the next section, that will contain a list of each of the jars for each of your crates. - Implement the
Dbtraits for each jar for your database typeD(often we do this through blanket impls in the jar crates).
- Define a database
Defining the database struct
Now that we have defined a jar, we need to create the database struct. The database struct is where all the jars come together. Typically it is only used by the "driver" of your application; the one which starts up the program, supplies the inputs, and relays the outputs.
In calc, the database struct is in the db module, and it looks like this:
#![allow(unused)] fn main() { #[derive(Default)] #[salsa::db(crate::Jar)] pub(crate) struct Database { storage: salsa::Storage<Self>, // The logs are only used for testing and demonstrating reuse: // logs: Option<Arc<Mutex<Vec<String>>>>, } }
The #[salsa::db(...)] attribute takes a list of all the jars to include.
The struct must have a field named storage whose type is salsa::Storage<Self>, but it can also contain whatever other fields you want.
The storage struct owns all the data for the jars listed in the db attribute.
The salsa::db attribute autogenerates a bunch of impls for things like the salsa::HasJar<crate::Jar> trait that we saw earlier.
Implementing the salsa::Database trait
In addition to the struct itself, we must add an impl of salsa::Database:
#![allow(unused)] fn main() { impl salsa::Database for Database { fn salsa_event(&self, event: salsa::Event) { eprintln!("Event: {event:?}"); // Log interesting events, if logging is enabled if let Some(logs) = &self.logs { // don't log boring events if let salsa::EventKind::WillExecute { .. } = event.kind { logs.lock() .unwrap() .push(format!("Event: {:?}", event.debug(self))); } } } } }
Implementing the salsa::ParallelDatabase trait
If you want to permit accessing your database from multiple threads at once, then you also need to implement the ParallelDatabase trait:
#![allow(unused)] fn main() { impl salsa::ParallelDatabase for Database { fn snapshot(&self) -> salsa::Snapshot<Self> { salsa::Snapshot::new(Database { storage: self.storage.snapshot(), logs: self.logs.clone(), }) } } }
Implementing the traits for each jar
The Database struct also needs to implement the database traits for each jar.
In our case, though, we already wrote that impl as a blanket impl alongside the jar itself,
so no action is needed.
This is the recommended strategy unless your trait has custom members that depend on fields of the Database itself
(for example, sometimes the Database holds some kind of custom resource that you want to give access to).
Defining the IR
Before we can define the parser, we need to define the intermediate representation (IR) that we will use for calc programs.
In the basic structure, we defined some "pseudo-Rust" structures like Statement and Expression;
now we are going to define them for real.
"Salsa structs"
In addition to regular Rust types, we will make use of various Salsa structs. A Salsa struct is a struct that has been annotated with one of the Salsa annotations:
#[salsa::input], which designates the "base inputs" to your computation;#[salsa::tracked], which designate intermediate values created during your computation;#[salsa::interned], which designate small values that are easy to compare for equality.
All Salsa structs store the actual values of their fields in the Salsa database. This permits us to track when the values of those fields change to figure out what work will need to be re-executed.
When you annotate a struct with one of the above Salsa attributes, Salsa actually generates a bunch of code to link that struct into the database.
This code must be connected to some jar.
By default, this is crate::Jar, but you can specify a different jar with the jar= attribute (e.g., #[salsa::input(jar = MyJar)]).
You must also list the struct in the jar definition itself, or you will get errors.
Input structs
The first thing we will define is our input. Every Salsa program has some basic inputs that drive the rest of the computation. The rest of the program must be some deterministic function of those base inputs, such that when those inputs change, we can try to efficiently recompute the new result of that function.
Inputs are defined as Rust structs with a #[salsa::input] annotation:
#![allow(unused)] fn main() { #[salsa::input] pub struct SourceProgram { #[return_ref] pub text: String, } }
In our compiler, we have just one simple input, the SourceProgram, which has a text field (the string).
The data lives in the database
Although they are declared like other Rust structs, Salsa structs are implemented quite differently.
The values of their fields are stored in the Salsa database, and the struct itself just contains a numeric identifier.
This means that the struct instances are copy (no matter what fields they contain).
Creating instances of the struct and accessing fields is done by invoking methods like new as well as getters and setters.
More concretely, the #[salsa::input] annotation will generate a struct for SourceProgram like this:
#![allow(unused)] fn main() { #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct SourceProgram(salsa::Id); }
It will also generate a method new that lets you create a SourceProgram in the database.
For an input, a &mut db reference is required, along with the values for each field:
#![allow(unused)] fn main() { let source = SourceProgram::new(&mut db, "print 11 + 11".to_string()); }
You can read the value of the field with source.text(&db),
and you can set the value of the field with source.set_text(&mut db, "print 11 * 2".to_string()).
Database revisions
Whenever a function takes an &mut reference to the database,
that means that it can only be invoked from outside the incrementalized part of your program,
as explained in the overview.
When you change the value of an input field, that increments a 'revision counter' in the database,
indicating that some inputs are different now.
When we talk about a "revision" of the database, we are referring to the state of the database in between changes to the input values.
Representing the parsed program
Next we will define a tracked struct. Whereas inputs represent the start of a computation, tracked structs represent intermediate values created during your computation.
In this case, the parser is going to take in the SourceProgram struct that we saw and return a Program that represents the fully parsed program:
#![allow(unused)] fn main() { #[salsa::tracked] pub struct Program { #[return_ref] pub statements: Vec<Statement>, } }
Like with an input, the fields of a tracked struct are also stored in the database.
Unlike an input, those fields are immutable (they cannot be "set"), and Salsa compares them across revisions to know when they have changed.
In this case, if parsing the input produced the same Program result (e.g., because the only change to the input was some trailing whitespace, perhaps),
then subsequent parts of the computation won't need to re-execute.
(We'll revisit the role of tracked structs in reuse more in future parts of the IR.)
Apart from the fields being immutable, the API for working with a tracked struct is quite similar to an input:
- You can create a new value by using
new, but with a tracked struct, you only need an&dyndatabase, not&mut(e.g.,Program::new(&db, some_staements)) - You use a getter to read the value of a field, just like with an input (e.g.,
my_func.statements(db)to read thestatementsfield).- In this case, the field is tagged as
#[return_ref], which means that the getter will return a&Vec<Statement>, instead of cloning the vector.
- In this case, the field is tagged as
Representing functions
We will also use a tracked struct to represent each function:
The Function struct is going to be created by the parser to represent each of the functions defined by the user:
#![allow(unused)] fn main() { #[salsa::tracked] pub struct Function { #[id] pub name: FunctionId, name_span: Span, #[return_ref] pub args: Vec<VariableId>, #[return_ref] pub body: Expression, } }
If we had created some Function instance f, for example, we might find that the f.body field changes
because the user changed the definition of f.
This would mean that we have to re-execute those parts of the code that depended on f.body
(but not those parts of the code that depended on the body of other functions).
Apart from the fields being immutable, the API for working with a tracked struct is quite similar to an input:
- You can create a new value by using
new, but with a tracked struct, you only need an&dyndatabase, not&mut(e.g.,Function::new(&db, some_name, some_args, some_body)) - You use a getter to read the value of a field, just like with an input (e.g.,
my_func.args(db)to read theargsfield).
id fields
To get better reuse across revisions, particularly when things are reordered, you can mark some entity fields with #[id].
Normally, you would do this on fields that represent the "name" of an entity.
This indicates that, across two revisions R1 and R2, if two functions are created with the same name, they refer to the same entity, so we can compare their other fields for equality to determine what needs to be re-executed.
Adding #[id] attributes is an optimization and never affects correctness.
For more details, see the algorithm page of the reference.
Interned structs
The final kind of Salsa struct are interned structs. As with input and tracked structs, the data for an interned struct is stored in the database, and you just pass around a single integer. Unlike those structs, if you intern the same data twice, you get back the same integer.
A classic use of interning is for small strings like function names and variables.
It's annoying and inefficient to pass around those names with String values which must be cloned;
it's also inefficient to have to compare them for equality via string comparison.
Therefore, we define two interned structs, FunctionId and VariableId, each with a single field that stores the string:
#![allow(unused)] fn main() { #[salsa::interned] pub struct VariableId { #[return_ref] pub text: String, } #[salsa::interned] pub struct FunctionId { #[return_ref] pub text: String, } }
When you invoke e.g. FunctionId::new(&db, "my_string".to_string()), you will get back a FunctionId that is just a newtype'd integer.
But if you invoke the same call to new again, you get back the same integer:
#![allow(unused)] fn main() { let f1 = FunctionId::new(&db, "my_string".to_string()); let f2 = FunctionId::new(&db, "my_string".to_string()); assert_eq!(f1, f2); }
Interned ids are guaranteed to be consistent within a revision, but not across revisions (but you don't have to care)
Interned ids are guaranteed not to change within a single revision, so you can intern things from all over your program and get back consistent results. When you change the inputs, however, Salsa may opt to clear some of the interned values and choose different integers. However, if this happens, it will also be sure to re-execute every function that interned that value, so all of them still see a consistent value, just a different one than they saw in a previous revision.
In other words, within a Salsa computation, you can assume that interning produces a single consistent integer, and you don't have to think about it. If, however, you export interned identifiers outside the computation, and then change the inputs, they may no longer be valid or may refer to different values.
Expressions and statements
We won't use any special "Salsa structs" for expressions and statements:
#![allow(unused)] fn main() { #[derive(Eq, PartialEq, Debug, Hash, new)] pub struct Statement { pub span: Span, pub data: StatementData, } #[derive(Eq, PartialEq, Debug, Hash)] pub enum StatementData { /// Defines `fn <name>(<args>) = <body>` Function(Function), /// Defines `print <expr>` Print(Expression), } #[derive(Eq, PartialEq, Debug, Hash, new)] pub struct Expression { pub span: Span, pub data: ExpressionData, } #[derive(Eq, PartialEq, Debug, Hash)] pub enum ExpressionData { Op(Box<Expression>, Op, Box<Expression>), Number(OrderedFloat<f64>), Variable(VariableId), Call(FunctionId, Vec<Expression>), } #[derive(Eq, PartialEq, Copy, Clone, Hash, Debug)] pub enum Op { Add, Subtract, Multiply, Divide, } }
Since statements and expressions are not tracked, this implies that we are only attempting to get incremental re-use at the granularity of functions -- whenever anything in a function body changes, we consider the entire function body dirty and re-execute anything that depended on it. It usually makes sense to draw some kind of "reasonably coarse" boundary like this.
One downside of the way we have set things up: we inlined the position into each of the structs.
Defining the parser: memoized functions and inputs
The next step in the calc compiler is to define the parser.
The role of the parser will be to take the ProgramSource input,
read the string from the text field,
and create the Statement, Function, and Expression structures that we defined in the ir module.
To minimize dependencies, we are going to write a recursive descent parser. Another option would be to use a Rust parsing framework. We won't cover the parsing itself in this tutorial -- you can read the code if you want to see how it works. We're going to focus only on the Salsa-related aspects.
The parse_statements function
The starting point for the parser is the parse_statements function:
#![allow(unused)] fn main() { #[salsa::tracked] pub fn parse_statements(db: &dyn crate::Db, source: SourceProgram) -> Program { // Get the source text from the database let source_text = source.text(db); // Create the parser let mut parser = Parser { db, source_text, position: 0, }; // Read in statements until we reach the end of the input let mut result = vec![]; loop { // Skip over any whitespace parser.skip_whitespace(); // If there are no more tokens, break if parser.peek().is_none() { break; } // Otherwise, there is more input, so parse a statement. if let Some(statement) = parser.parse_statement() { result.push(statement); } else { // If we failed, report an error at whatever position the parser // got stuck. We could recover here by skipping to the end of the line // or something like that. But we leave that as an exercise for the reader! parser.report_error(); break; } } Program::new(db, result) } }
This function is annotated as #[salsa::tracked].
That means that, when it is called, Salsa will track what inputs it reads as well as what value it returns.
The return value is memoized,
which means that if you call this function again without changing the inputs,
Salsa will just clone the result rather than re-execute it.
Tracked functions are the unit of reuse
Tracked functions are the core part of how Salsa enables incremental reuse.
The goal of the framework is to avoid re-executing tracked functions and instead to clone their result.
Salsa uses the red-green algorithm to decide when to re-execute a function.
The short version is that a tracked function is re-executed if either (a) it directly reads an input, and that input has changed,
or (b) it directly invokes another tracked function and that function's return value has changed.
In the case of parse_statements, it directly reads ProgramSource::text, so if the text changes, then the parser will re-execute.
By choosing which functions to mark as #[tracked], you control how much reuse you get.
In our case, we're opting to mark the outermost parsing function as tracked, but not the inner ones.
This means that if the input changes, we will always re-parse the entire input and re-create the resulting statements and so forth.
We'll see later that this doesn't mean we will always re-run the type checker and other parts of the compiler.
This trade-off makes sense because (a) parsing is very cheap, so the overhead of tracking and enabling finer-grained reuse doesn't pay off and because (b) since strings are just a big blob-o-bytes without any structure, it's rather hard to identify which parts of the IR need to be reparsed. Some systems do choose to do more granular reparsing, often by doing a "first pass" over the string to give it a bit of structure, e.g. to identify the functions, but deferring the parsing of the body of each function until later. Setting up a scheme like this is relatively easy in Salsa and uses the same principles that we will use later to avoid re-executing the type checker.
Parameters to a tracked function
The first parameter to a tracked function is always the database, db: &dyn crate::Db.
It must be a dyn value of whatever database is associated with the jar.
The second parameter to a tracked function is always some kind of Salsa struct.
The first parameter to a memoized function is always the database,
which should be a dyn Trait value for the database trait associated with the jar
(the default jar is crate::Jar).
Tracked functions may take other arguments as well, though our examples here do not. Functions that take additional arguments are less efficient and flexible. It's generally better to structure tracked functions as functions of a single Salsa struct if possible.
The return_ref annotation
You may have noticed that parse_statements is tagged with #[salsa::tracked(return_ref)].
Ordinarily, when you call a tracked function, the result you get back is cloned out of the database.
The return_ref attribute means that a reference into the database is returned instead.
So, when called, parse_statements will return an &Vec<Statement> rather than cloning the Vec.
This is useful as a performance optimization.
(You may recall the return_ref annotation from the ir section of the tutorial,
where it was placed on struct fields, with roughly the same meaning.)
Defining the parser: reporting errors
The last interesting case in the parser is how to handle a parse error.
Because Salsa functions are memoized and may not execute, they should not have side-effects,
so we don't just want to call eprintln!.
If we did so, the error would only be reported the first time the function was called, but not
on subsequent calls in the situation where the simply returns its memoized value.
Salsa defines a mechanism for managing this called an accumulator.
In our case, we define an accumulator struct called Diagnostics in the ir module:
#![allow(unused)] fn main() { #[salsa::accumulator] pub struct Diagnostics(Diagnostic); #[derive(new, Clone, Debug)] pub struct Diagnostic { pub start: usize, pub end: usize, pub message: String, } }
Accumulator structs are always newtype structs with a single field, in this case of type Diagnostic.
Memoized functions can push Diagnostic values onto the accumulator.
Later, you can invoke a method to find all the values that were pushed by the memoized functions
or any functions that they called
(e.g., we could get the set of Diagnostic values produced by the parse_statements function).
The Parser::report_error method contains an example of pushing a diagnostic:
#![allow(unused)] fn main() { /// Report an error diagnostic at the current position. fn report_error(&self) { let next_position = match self.peek() { Some(ch) => self.position + ch.len_utf8(), None => self.position, }; Diagnostics::push( self.db, Diagnostic { start: self.position, end: next_position, message: "unexpected character".to_string(), }, ); } }
To get the set of diagnostics produced by parse_errors, or any other memoized function,
we invoke the associated accumulated function:
#![allow(unused)] fn main() { let accumulated: Vec<Diagnostic> = parse_statements::accumulated::<Diagnostics>(db); // ----------- // Use turbofish to specify // the diagnostics type. }
accumulated takes the database db as argument and returns a Vec.
Defining the parser: debug impls and testing
As the final part of the parser, we need to write some tests.
To do so, we will create a database, set the input source text, run the parser, and check the result.
Before we can do that, though, we have to address one question: how do we inspect the value of an interned type like Expression?
The DebugWithDb trait
Because an interned type like Expression just stores an integer, the traditional Debug trait is not very useful.
To properly print a Expression, you need to access the Salsa database to find out what its value is.
To solve this, salsa provides a DebugWithDb trait that acts like the regular Debug, but takes a database as argument.
For types that implement this trait, you can invoke the debug method.
This returns a temporary that implements the ordinary Debug trait, allowing you to write something like
#![allow(unused)] fn main() { eprintln!("Expression = {:?}", expr.debug(db)); }
and get back the output you expect.
The DebugWithDb trait is automatically derived for all #[input], #[interned], and #[tracked] structs.
Forwarding to the ordinary Debug trait
For consistency, it is sometimes useful to have a DebugWithDb implementation even for types, like Op, that are just ordinary enums. You can do that like so:
#![allow(unused)] fn main() { }
Writing the unit test
Now that we have our DebugWithDb impls in place, we can write a simple unit test harness.
The parse_string function below creates a database, sets the source text, and then invokes the parser:
#![allow(unused)] fn main() { /// Create a new database with the given source text and parse the result. /// Returns the statements and the diagnostics generated. #[cfg(test)] fn parse_string(source_text: &str) -> String { use salsa::debug::DebugWithDb; // Create the database let db = crate::db::Database::default(); // Create the source program let source_program = SourceProgram::new(&db, source_text.to_string()); // Invoke the parser let statements = parse_statements(&db, source_program); // Read out any diagnostics let accumulated = parse_statements::accumulated::<Diagnostics>(&db, source_program); // Format the result as a string and return it format!("{:#?}", (statements.debug(&db), accumulated)) } }
Combined with the expect-test crate, we can then write unit tests like this one:
#![allow(unused)] fn main() { #[test] fn parse_print() { let actual = parse_string("print 1 + 2"); let expected = expect_test::expect![[r#" ( Program { [salsa id]: 0, statements: [ Statement { span: Span( Id { value: 5, }, ), data: Print( Expression { span: Span( Id { value: 4, }, ), data: Op( Expression { span: Span( Id { value: 1, }, ), data: Number( OrderedFloat( 1.0, ), ), }, Add, Expression { span: Span( Id { value: 3, }, ), data: Number( OrderedFloat( 2.0, ), ), }, ), }, ), }, ], }, [], )"#]]; expected.assert_eq(&actual); } }
Defining the checker
Defining the interpreter
Reference
The "red-green" algorithm
This page explains the basic Salsa incremental algorithm. The algorithm is called the "red-green" algorithm, which is where the name Salsa comes from.
Database revisions
The Salsa database always tracks a single revision. Each time you set an input, the revision is incremented. So we start in revision R1, but when a set method is called, we will go to R2, then R3, and so on. For each input, we also track the revision in which it was last changed.
Basic rule: when inputs change, re-execute!
When you invoke a tracked function, in addition to storing the value that was returned, we also track what other tracked functions it depends on, and the revisions when their value last changed. When you invoke the function again, if the database is in a new revision, then we check whether any of the inputs to this function have changed in that new revision. If not, we can just return our cached value. But if the inputs have changed (or may have changed), we will re-execute the function to find the most up-to-date answer.
Here is a simple example, where the parse_module function invokes the module_text function:
#![allow(unused)] fn main() { #[salsa::tracked] fn parse_module(db: &dyn Db, module: Module) -> Ast { let module_text: &String = module_text(db, module); Ast::parse_text(module_text) } #[salsa::tracked(return_ref)] fn module_text(db: &dyn Db, module: Module) -> String { panic!("text for module `{module:?}` not set") } }
If we invoke parse_module twice, but change the module text in between, then we will have to re-execute parse_module:
#![allow(unused)] fn main() { module_text::set( db, module, "fn foo() { }".to_string(), ); parse_module(db, module); // executes // ...some time later... module_text::set( db, module, "fn foo() { /* add a comment */ }".to_string(), ); parse_module(db, module); // executes again! }
Backdating: sometimes we can be smarter
Often, though, tracked functions don't depend directly on the inputs. Instead, they'll depend on some other tracked function. For example, perhaps we have a type_check function that reads the AST:
#![allow(unused)] fn main() { #[salsa::tracked] fn type_check(db: &dyn Db, module: Module) { let ast = parse_module(db, module); ... } }
If the module text is changed, we saw that we have to re-execute parse_module, but there are many changes to the source text that still produce the same AST. For example, suppose we simply add a comment? In that case, if type_check is called again, we will:
- First re-execute
parse_module, since its input changed. - We will then compare the resulting AST. If it's the same as last time, we can backdate the result, meaning that we say that, even though the inputs changed, the output didn't.
Durability: an optimization
As an optimization, Salsa includes the concept of durability, which is the notion of how often some piece of tracked data changes.
For example, when compiling a Rust program, you might mark the inputs from crates.io as high durability inputs, since they are unlikely to change. The current workspace could be marked as low durability, since changes to it are happening all the time.
When you set the value of a tracked function, you can also set it with a given durability:
#![allow(unused)] fn main() { module_text::set_with_durability( db, module, "fn foo() { }".to_string(), salsa::Durability::HIGH ); }
For each durability, we track the revision in which some input with that durability changed. If a tracked function depends (transitively) only on high durability inputs, and you change a low durability input, then we can very easily determine that the tracked function result is still valid, avoiding the need to traverse the input edges one by one.
Common patterns
This section documents patterns for using Salsa.
Selection
The "selection" (or "firewall") pattern is when you have a query Qsel that reads from some other Qbase and extracts some small bit of information from Qbase that it returns. In particular, Qsel does not combine values from other queries. In some sense, then, Qsel is redundant -- you could have just extracted the information the information from Qbase yourself, and done without the salsa machinery. But Qsel serves a role in that it limits the amount of re-execution that is required when Qbase changes.
Example: the base query
For example, imagine that you have a query parse that parses the input text of a request
and returns a ParsedResult, which contains a header and a body:
#[derive(Clone, Debug, PartialEq, Eq)]
struct ParsedResult {
header: Vec<ParsedHeader>,
body: String,
}
#[derive(Clone, Debug, PartialEq, Eq)]
struct ParsedHeader {
key: String,
value: String,
}
#[salsa::query_group(Request)]
trait RequestParser {
/// The base text of the request.
#[salsa::input]
fn request_text(&self) -> String;
/// The parsed form of the request.
fn parse(&self) -> ParsedResult;
}
Example: a selecting query
And now you have a number of derived queries that only look at the header. For example, one might extract the "content-type' header:
#[salsa::query_group(Request)]
trait RequestUtil: RequestParser {
fn content_type(&self) -> Option<String>;
}
fn content_type(db: &dyn RequestUtil) -> Option<String> {
db.parse()
.header
.iter()
.find(|header| header.key == "content-type")
.map(|header| header.value.clone())
}
Why prefer a selecting query?
This content_type query is an instance of the selection pattern. It only
"selects" a small bit of information from the ParsedResult. You might not have
made it a query at all, but instead made it a method on ParsedResult.
But using a query for content_type has an advantage: now if there are downstream
queries that only depend on the content_type (or perhaps on other headers extracted
via a similar pattern), those queries will not have to be re-executed when the request
changes unless the content-type header changes. Consider the dependency graph:
request_text --> parse --> content_type --> (other queries)
When the request_text changes, we are always going to have to re-execute parse.
If that produces a new parsed result, we are also going to re-execute content_type.
But if the result of content_type has not changed, then we will not re-execute
the other queries.
More levels of selection
In fact, in our example we might consider introducing another level of selection.
Instead of having content_type directly access the results of parse, it might be better
to insert a selecting query that just extracts the header:
#[salsa::query_group(Request)]
trait RequestUtil: RequestParser {
fn header(&self) -> Vec<ParsedHeader>;
fn content_type(&self) -> Option<String>;
}
fn header(db: &dyn RequestUtil) -> Vec<ParsedHeader> {
db.parse().header
}
fn content_type(db: &dyn RequestUtil) -> Option<String> {
db.header()
.iter()
.find(|header| header.key == "content-type")
.map(|header| header.value.clone())
}
This will result in a dependency graph like so:
request_text --> parse --> header --> content_type --> (other queries)
The advantage of this is that changes that only effect the "body" or
only consume small parts of the request will
not require us to re-execute content_type at all. This would be particularly
valuable if there are a lot of dependent headers.
A note on cloning and efficiency
In this example, we used common Rust types like Vec and String,
and we cloned them quite frequently. This will work just fine in Salsa,
but it may not be the most efficient choice. This is because each clone
is going to produce a deep copy of the result. As a simple fix, you
might convert your data structures to use Arc (e.g., Arc<Vec<ParsedHeader>>),
which makes cloning cheap.
On-Demand (Lazy) Inputs
⚠️ IN-PROGRESS VERSION OF SALSA. ⚠️
This page describes the unreleased "Salsa 2022" version, which is a major departure from older versions of salsa. The code here works but is only available on github and from the
salsa-2022crate.If you are looking for the older version of salsa, simply visit this link
Salsa inputs work best if you can easily provide all of the inputs upfront. However sometimes the set of inputs is not known beforehand.
A typical example is reading files from disk. While it is possible to eagerly scan a particular directory and create an in-memory file tree as salsa input structs, a more straight-forward approach is to read the files lazily. That is, when a query requests the text of a file for the first time:
- Read the file from disk and cache it.
- Setup a file-system watcher for this path.
- Update the cached file when the watcher sends a change notification.
This is possible to achieve in salsa, by caching the inputs in your database structs and adding a method to the database trait to retrieve them out of this cache.
A complete, runnable file-watching example can be found in the lazy-input example.
The setup looks roughly like this:
#[salsa::input]
struct File {
path: PathBuf,
#[return_ref]
contents: String,
}
trait Db: salsa::DbWithJar<Jar> {
fn input(&self, path: PathBuf) -> Result<File>;
}
#[salsa::db(Jar)]
struct Database {
storage: salsa::Storage<Self>,
logs: Mutex<Vec<String>>,
files: DashMap<PathBuf, File>,
file_watcher: Mutex<Debouncer<RecommendedWatcher>>,
}
impl Database {
fn new(tx: Sender<DebounceEventResult>) -> Self {
let storage = Default::default();
Self {
storage,
logs: Default::default(),
files: DashMap::new(),
file_watcher: Mutex::new(new_debouncer(Duration::from_secs(1), None, tx).unwrap()),
}
}
}
impl Db for Database {
fn input(&self, path: PathBuf) -> Result<File> {
let path = path
.canonicalize()
.wrap_err_with(|| format!("Failed to read {}", path.display()))?;
Ok(match self.files.entry(path.clone()) {
// If the file already exists in our cache then just return it.
Entry::Occupied(entry) => *entry.get(),
// If we haven't read this file yet set up the watch, read the
// contents, store it in the cache, and return it.
Entry::Vacant(entry) => {
// Set up the watch before reading the contents to try to avoid
// race conditions.
let watcher = &mut *self.file_watcher.lock().unwrap();
watcher
.watcher()
.watch(&path, RecursiveMode::NonRecursive)
.unwrap();
let contents = std::fs::read_to_string(&path)
.wrap_err_with(|| format!("Failed to read {}", path.display()))?;
*entry.insert(File::new(self, path, contents))
}
})
}
}
- We declare a method on the
Dbtrait that gives us aFileinput on-demand (it only requires a&dyn Dbnot a&mut dyn Db). - There should only be one input struct per file, so we implement that method using a cache (
DashMapis like aRwLock<HashMap>).
The driving code that's doing the top-level queries is then in charge of updating the file contents when a file-change notification arrives. It does this by updating the Salsa input in the same way that you would update any other input.
Here we implement a simple driving loop, that recompiles the code whenever a file changes. You can use the logs to check that only the queries that could have changed are re-evaluated.
fn main() -> Result<()> {
// Create the channel to receive file change events.
let (tx, rx) = unbounded();
let mut db = Database::new(tx);
let initial_file_path = std::env::args_os()
.nth(1)
.ok_or_else(|| eyre!("Usage: ./lazy-input <input-file>"))?;
// Create the initial input using the input method so that changes to it
// will be watched like the other files.
let initial = db.input(initial_file_path.into())?;
loop {
// Compile the code starting at the provided input, this will read other
// needed files using the on-demand mechanism.
let sum = compile(&db, initial);
let diagnostics = compile::accumulated::<Diagnostic>(&db, initial);
if diagnostics.is_empty() {
println!("Sum is: {}", sum);
} else {
for diagnostic in diagnostics {
println!("{}", diagnostic);
}
}
for log in db.logs.lock().unwrap().drain(..) {
eprintln!("{}", log);
}
// Wait for file change events, the output can't change unless the
// inputs change.
for event in rx.recv()?.unwrap() {
let path = event.path.canonicalize().wrap_err_with(|| {
format!("Failed to canonicalize path {}", event.path.display())
})?;
let file = match db.files.get(&path) {
Some(file) => *file,
None => continue,
};
// `path` has changed, so read it and update the contents to match.
// This creates a new revision and causes the incremental algorithm
// to kick in, just like any other update to a salsa input.
let contents = std::fs::read_to_string(path)
.wrap_err_with(|| format!("Failed to read file {}", event.path.display()))?;
file.set_contents(&mut db).to(contents);
}
}
}
Tuning Salsa
LRU Cache
You can specify an LRU cache size for any non-input query:
let lru_capacity: usize = 128;
base_db::ParseQuery.in_db_mut(self).set_lru_capacity(lru_capacity);
The default is 0, which disables LRU-caching entirely.
Note that there is no garbage collection for keys and results of old queries, so LRU caches are currently the only knob available for avoiding unbounded memory usage for long-running apps built on Salsa.
Intern Queries
Intern queries can make key lookup cheaper, save memory, and
avoid the need for Arc.
Interning is especially useful for queries that involve nested, tree-like data structures.
See:
- The
compilerexample, which uses interning.
Granularity of Incrementality
See:
Cancellation
Queries that are no longer needed due to concurrent writes or changes in dependencies are cancelled by Salsa. Each access of an intermediate query is a potential cancellation point. Cancellation is implemented via panicking, and Salsa internals are intended to be panic-safe.
If you have a query that contains a long loop which does not execute any intermediate queries,
salsa won't be able to cancel it automatically. You may wish to check for cancellation yourself
by invoking db.unwind_if_cancelled().
For more details on cancellation, see the tests for cancellation behavior in the Salsa repo.
Cycle handling
By default, when Salsa detects a cycle in the computation graph, Salsa will panic with a salsa::Cycle as the panic value. The salsa::Cycle structure that describes the cycle, which can be useful for diagnosing what went wrong.
Recovering via fallback
Panicking when a cycle occurs is ok for situations where you believe a cycle is impossible. But sometimes cycles can result from illegal user input and cannot be statically prevented. In these cases, you might prefer to gracefully recover from a cycle rather than panicking the entire query. Salsa supports that with the idea of cycle recovery.
To use cycle recovery, you annotate potential participants in the cycle with a #[salsa::cycle(my_recover_fn)] attribute. When a cycle occurs, if any participant P has recovery information, then no panic occurs. Instead, the execution of P is aborted and P will execute the recovery function to generate its result. Participants in the cycle that do not have recovery information continue executing as normal, using this recovery result.
The recovery function has a similar signature to a query function. It is given a reference to your database along with a salsa::Cycle describing the cycle that occurred; it returns the result of the query. Example:
#![allow(unused)] fn main() { fn my_recover_fn( db: &dyn MyDatabase, cycle: &salsa::Cycle, ) -> MyResultValue }
The db and cycle argument can be used to prepare a useful error message for your users.
Important: Although the recovery function is given a db handle, you should be careful to avoid creating a cycle from within recovery or invoking queries that may be participating in the current cycle. Attempting to do so can result in inconsistent results.
Figuring out why recovery did not work
If a cycle occurs and some of the participant queries have #[salsa::cycle] annotations and others do not, then the query will be treated as irrecoverable and will simply panic. You can use the Cycle::unexpected_participants method to figure out why recovery did not succeed and add the appropriate #[salsa::cycle] annotations.
How Salsa works
Video available
To get the most complete introduction to Salsa's inner workings, check out the "How Salsa Works" video. If you'd like a deeper dive, the "Salsa in more depth" video digs into the details of the incremental algorithm.
If you're in China, watch videos on "How Salsa Works", "Salsa In More Depth".
Key idea
The key idea of salsa is that you define your program as a set of
queries. Every query is used like a function K -> V that maps from
some key of type K to a value of type V. Queries come in two basic
varieties:
- Inputs: the base inputs to your system. You can change these whenever you like.
- Functions: pure functions (no side effects) that transform your inputs into other values. The results of queries are memoized to avoid recomputing them a lot. When you make changes to the inputs, we'll figure out (fairly intelligently) when we can re-use these memoized values and when we have to recompute them.
How to use Salsa in three easy steps
Using Salsa is as easy as 1, 2, 3...
- Define one or more query groups that contain the inputs and queries you will need. We'll start with one such group, but later on you can use more than one to break up your system into components (or spread your code across crates).
- Define the query functions where appropriate.
- Define the database, which contains the storage for all the inputs/queries you will be using. The query struct will contain the storage for all of the inputs/queries and may also contain anything else that your code needs (e.g., configuration data).
To see an example of this in action, check out the hello_world
example, which has a number of comments explaining how
things work.
Digging into the plumbing
Check out the plumbing chapter to see a deeper explanation of the code that Salsa generates and how it connects to the Salsa library.
Videos
There is currently one video available on the newest version of Salsa:
- Salsa Architecture Walkthrough, which covers many aspects of the redesigned architecture.
There are also two videos on the older version Salsa, but they are rather outdated:
- How Salsa Works, which gives a high-level introduction to the key concepts involved and shows how to use Salsa;
- Salsa In More Depth, which digs into the incremental algorithm and explains -- at a high-level -- how Salsa is implemented.
If you're in China, watch videos on How Salsa Works, Salsa In More Depth.
Plumbing
⚠️ IN-PROGRESS VERSION OF SALSA. ⚠️
This page describes the unreleased "Salsa 2022" version, which is a major departure from older versions of salsa. The code here works but is only available on github and from the
salsa-2022crate.If you are looking for the older version of salsa, simply visit this link
This chapter documents the code that salsa generates and its "inner workings". We refer to this as the "plumbing".
Overview
The plumbing section is broken up into chapters:
- The jars and ingredients covers how each salsa item (like a tracked function) specifies what data it needs and runtime, and how links between items work.
- The database and runtime covers the data structures that are used at runtime to coordinate workers, trigger cancellation, track which functions are active and what dependencies they have accrued, and so forth.
- The query operations chapter describes how the major operations on function ingredients work. This text was written for an older version of salsa but the logic is the same:
- The maybe changed after operation determines when a memoized value for a tracked function is out of date.
- The fetch operation computes the most recent value.
- The derived queries flowchart depicts the logic in flowchart form.
- The cycle handling handling chapter describes what happens when cycles occur.
- The terminology section describes various words that appear throughout.
Jars and ingredients
⚠️ IN-PROGRESS VERSION OF SALSA. ⚠️
This page describes the unreleased "Salsa 2022" version, which is a major departure from older versions of salsa. The code here works but is only available on github and from the
salsa-2022crate.If you are looking for the older version of salsa, simply visit this link
This page covers how data is organized in Salsa and how links between Salsa items (e.g., dependency tracking) work.
Salsa items and ingredients
A Salsa item is some item annotated with a Salsa annotation that can be included in a jar. For example, a tracked function is a Salsa item:
#![allow(unused)] fn main() { #[salsa::tracked] fn foo(db: &dyn Db, input: MyInput) { } }
...and so is a Salsa input...
#![allow(unused)] fn main() { #[salsa::input] struct MyInput { } }
...or a tracked struct:
#![allow(unused)] fn main() { #[salsa::tracked] struct MyStruct { } }
Each Salsa item needs certain bits of data at runtime to operate.
These bits of data are called ingredients.
Most Salsa items generate a single ingredient, but sometimes they make more than one.
For example, a tracked function generates a FunctionIngredient.
A tracked struct, however, generates several ingredients, one for the struct itself (a TrackedStructIngredient,
and one FunctionIngredient for each value field.
Ingredients define the core logic of Salsa
Most of the interesting Salsa code lives in these ingredients.
For example, when you create a new tracked struct, the method TrackedStruct::new_struct is invoked;
it is responsible for determining the tracked struct's id.
Similarly, when you call a tracked function, that is translated into a call to TrackedFunction::fetch,
which decides whether there is a valid memoized value to return,
or whether the function must be executed.
The Ingredient trait
Each ingredient implements the Ingredient<DB> trait, which defines generic operations supported by any kind of ingredient.
For example, the method maybe_changed_after can be used to check whether some particular piece of data stored in the ingredient may have changed since a given revision:
We'll see below that each database DB is able to take an IngredientIndex and use that to get an &dyn Ingredient<DB> for the corresponding ingredient.
This allows the database to perform generic operations on an indexed ingredient without knowing exactly what the type of that ingredient is.
Jars are a collection of ingredients
When you declare a Salsa jar, you list out each of the Salsa items that are included in that jar:
#[salsa::jar]
struct Jar(
foo,
MyInput,
MyStruct
);
This expands to a struct like so:
#![allow(unused)] fn main() { struct Jar( <foo as IngredientsFor>::Ingredient, <MyInput as IngredientsFor>::Ingredient, <MyStruct as IngredientsFor>::Ingredient, ) }
The IngredientsFor trait is used to define the ingredients needed by some Salsa item, such as the tracked function foo or the tracked struct MyInput.
Each Salsa item defines a type I so that <I as IngredientsFor>::Ingredient gives the ingredients needed by I.
A database is a tuple of jars
Salsa's database storage ultimately boils down to a tuple of jar structs where each jar struct (as we just saw) itself contains the ingredients for the Salsa items within that jar. The database can thus be thought of as a list of ingredients, although that list is organized into a 2-level hierarchy.
The reason for this 2-level hierarchy is that it permits separate compilation and privacy. The crate that lists the jars doens't have to know the contents of the jar to embed the jar struct in the database. And some of the types that appear in the jar may be private to another struct.
The HasJars trait and the Jars type
Each Salsa database implements the HasJars trait,
generated by the salsa::db procedural macro.
The HarJars trait, among other things, defines a Jars associated type that maps to a tuple of the jars in the trait.
For example, given a database like this...
#[salsa::db(Jar1, ..., JarN)]
struct MyDatabase {
storage: salsa::Storage<Self>
}
...the salsa::db macro would generate a HasJars impl that (among other things) contains type Jars = (Jar1, ..., JarN):
impl salsa::storage::HasJars for #db {
type Jars = (#(#jar_paths,)*);
In turn, the salsa::Storage<DB> type ultimately contains a struct Shared that embeds DB::Jars, thus embedding all the data for each jar.
Ingredient indices
During initialization, each ingredient in the database is assigned a unique index called the IngredientIndex.
This is a 32-bit number that identifies a particular ingredient from a particular jar.
Routes
In addition to an index, each ingredient in the database also has a corresponding route.
A route is a closure that, given a reference to the DB::Jars tuple,
returns a &dyn Ingredient<DB> reference.
The route table allows us to go from the IngredientIndex for a particular ingredient
to its &dyn Ingredient<DB> trait object.
The route table is created while the database is being initialized,
as described shortly.
Database keys and dependency keys
A DatabaseKeyIndex identifies a specific value stored in some specific ingredient.
It combines an IngredientIndex with a key_index, which is a salsa::Id:
/// An "active" database key index represents a database key index
/// that is actively executing. In that case, the `key_index` cannot be
/// None.
#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
pub struct DatabaseKeyIndex {
pub(crate) ingredient_index: IngredientIndex,
pub(crate) key_index: Id,
}
A DependencyIndex is similar, but the key_index is optional.
This is used when we sometimes wish to refer to the ingredient as a whole, and not any specific value within the ingredient.
These kinds of indices are used to store connetions between ingredients. For example, each memoized value has to track its inputs. Those inputs are stored as dependency indices. We can then do things like ask, "did this input change since revision R?" by
- using the ingredient index to find the route and get a
&dyn Ingredient<DB> - and then invoking the
maybe_changed_sincemethod on that trait object.
HasJarsDyn
There is one catch in the above setup.
The user's code always interacts with a dyn crate::Db value, where crate::Db is the trait defined by the jar; the crate::Db trait extends salsa::HasJar which in turn extends salsa::Database.
Ideally, we would have salsa::Database extend salsa::HasJars, which is the main trait that gives access to the jars data.
But we don't want to do that because HasJars defines an associated type Jars, and that would mean that every reference to dyn crate::Db would have to specify the jars type using something like dyn crate::Db<Jars = J>.
This would be unergonomic, but what's worse, it would actually be impossible: the final Jars type combines the jars from multiple crates, and so it is not known to any individual jar crate.
To workaround this, salsa::Database in fact extends another trait, HasJarsDyn, that doesn't reveal the Jars or ingredient types directly, but just has various method that can be performed on an ingredient, given its IngredientIndex.
Traits like Ingredient<DB> require knowing the full DB type.
If we had one function ingredient directly invoke a method on Ingredient<DB>, that would imply that it has to be fully generic and only instantiated at the final crate, when the full database type is available.
We solve this via the HasJarsDyn trait. The HasJarsDyn trait exports a method that combines the "find ingredient, invoking method" steps into one method:
/// Dyn friendly subset of HasJars
pub trait HasJarsDyn {
fn runtime(&self) -> &Runtime;
fn runtime_mut(&mut self) -> &mut Runtime;
fn maybe_changed_after(&self, input: DependencyIndex, revision: Revision) -> bool;
fn cycle_recovery_strategy(&self, input: IngredientIndex) -> CycleRecoveryStrategy;
fn origin(&self, input: DatabaseKeyIndex) -> Option<QueryOrigin>;
fn mark_validated_output(&self, executor: DatabaseKeyIndex, output: DependencyIndex);
/// Invoked when `executor` used to output `stale_output` but no longer does.
/// This method routes that into a call to the [`remove_stale_output`](`crate::ingredient::Ingredient::remove_stale_output`)
/// method on the ingredient for `stale_output`.
fn remove_stale_output(&self, executor: DatabaseKeyIndex, stale_output: DependencyIndex);
/// Informs `ingredient` that the salsa struct with id `id` has been deleted.
/// This means that `id` will not be used in this revision and hence
/// any memoized values keyed by that struct can be discarded.
///
/// In order to receive this callback, `ingredient` must have registered itself
/// as a dependent function using
/// [`SalsaStructInDb::register_dependent_fn`](`crate::salsa_struct::SalsaStructInDb::register_dependent_fn`).
fn salsa_struct_deleted(&self, ingredient: IngredientIndex, id: Id);
fn fmt_index(&self, index: DependencyIndex, fmt: &mut fmt::Formatter<'_>) -> fmt::Result;
}
So, technically, to check if an input has changed, an ingredient:
- Invokes
HasJarsDyn::maybe_changed_afteron thedyn Database - The impl for this method (generated by
#[salsa::db]):- gets the route for the ingredient from the ingredient index
- uses the route to get a
&dyn Ingredient - invokes
maybe_changed_afteron that ingredient
Initializing the database
The last thing to dicsuss is how the database is initialized.
The Default implementation for Storage<DB> does the work:
impl<DB> Default for Storage<DB>
where
DB: HasJars,
{
fn default() -> Self {
let mut routes = Routes::new();
let jars = DB::create_jars(&mut routes);
Self {
shared: Shared {
jars: Some(Arc::from(jars)),
cvar: Arc::new(Default::default()),
noti_lock: Arc::new(parking_lot::Mutex::new(())),
},
routes: Arc::new(routes),
runtime: Runtime::default(),
}
}
}
First, it creates an empty Routes instance.
Then it invokes the DB::create_jars method.
The implementation of this method is defined by the #[salsa::db] macro; it invokes salsa::plumbing::create_jars_inplace to allocate memory for the jars, and then invokes the Jar::init_jar method on each of the jars to initialize them:
fn create_jars(routes: &mut salsa::routes::Routes<Self>) -> Box<Self::Jars> {
unsafe {
salsa::plumbing::create_jars_inplace::<#db>(|jars| {
(
unsafe {
let place = std::ptr::addr_of_mut!((*jars).#jar_field_names);
<#jar_paths as salsa::jar::Jar>::init_jar(place, routes);
}
)*
})
}
}
This implementation for init_jar is generated by the #[salsa::jar] macro, and simply walks over the representative type for each salsa item and asks it to create its ingredients
quote! {
unsafe impl<'salsa_db> salsa::jar::Jar<'salsa_db> for #jar_struct {
type DynDb = dyn #jar_trait + 'salsa_db;
unsafe fn init_jar<DB>(place: *mut Self, routes: &mut salsa::routes::Routes<DB>)
where
DB: salsa::storage::JarFromJars<Self> + salsa::storage::DbWithJar<Self>,
{
(
unsafe {
std::ptr::addr_of_mut!((*place).#field_var_names)
.write(<#field_tys as salsa::storage::IngredientsFor>::create_ingredients(routes));
}
)*
}
}
}
The code to create the ingredients for any particular item is generated by their associated macros (e.g., #[salsa::tracked], #[salsa::input]), but it always follows a particular structure.
To create an ingredient, we first invoke Routes::push, which creates the routes to that ingredient and assigns it an IngredientIndex.
We can then invoke a function such as FunctionIngredient::new to create the structure.
The routes to an ingredient are defined as closures that, given the DB::Jars, can find the data for a particular ingredient.
Database and runtime
A salsa database struct is declared by the user with the #[salsa::db] annotation.
It contains all the data that the program needs to execute:
#[salsa::db(jar0...jarn)]
struct MyDatabase {
storage: Storage<Self>,
maybe_other_fields: u32,
}
This data is divided into two categories:
- Salsa-governed storage, contained in the
Storage<Self>field. This data is mandatory. - Other fields (like
maybe_other_fields) defined by the user. This can be anything. This allows for you to give access to special resources or whatever.
Parallel handles
When used across parallel threads, the database type defined by the user must support a "snapshot" operation.
This snapshot should create a clone of the database that can be used by the parallel threads.
The Storage operation itself supports snapshot.
The Snapshot method returns a Snapshot<DB> type, which prevents these clones from being accessed via an &mut reference.
The Storage struct
The salsa Storage struct contains all the data that salsa itself will use and work with.
There are three key bits of data:
- The
Sharedstruct, which contains the data stored across all snapshots. This is primarily the ingredients described in the jars and ingredients chapter, but it also contains some synchronization information (a cond var). This is used for cancellation, as described below.- The data in the
Sharedstruct is only shared across threads when other threads are active. Some operations, like mutating an input, require an&muthandle to theSharedstruct. This is obtained by using theArc::get_mutmethods; obviously this is only possible when all snapshots and threads have ceased executing, since there must be a single handle to theArc.
- The data in the
- The
Routesstruct, which contains the information to find any particular ingredient -- this is also shared across all handles, and its construction is also described in the jars and ingredients chapter. The routes are separated out from theSharedstruct because they are truly immutable at all times, and we want to be able to hold a handle to them while getting&mutaccess to theSharedstruct. - The
Runtimestruct, which is specific to a particular database instance. It contains the data for a single active thread, along with some links to shared data of its own.
Incrementing the revision counter and getting mutable access to the jars
Salsa's general model is that there is a single "master" copy of the database and, potentially, multiple snapshots.
The snapshots are not directly owned, they are instead enclosed in a Snapshot<DB> type that permits only &-deref,
and so the only database that can be accessed with an &mut-ref is the master database.
Each of the snapshots however onlys another handle on the Arc in Storage that stores the ingredients.
Whenever the user attempts to do an &mut-operation, such as modifying an input field, that needs to
first cancel any parallel snapshots and wait for those parallel threads to finish.
Once the snapshots have completed, we can use Arc::get_mut to get an &mut reference to the ingredient data.
This allows us to get &mut access without any unsafe code and
guarantees that we have successfully managed to cancel the other worker threads
(or gotten ourselves into a deadlock).
The code to acquire &mut access to the database is the jars_mut method:
#![allow(unused)] fn main() { /// Gets mutable access to the jars. This will trigger a new revision /// and it will also cancel any ongoing work in the current revision. /// Any actual writes that occur to data in a jar should use /// [`Runtime::report_tracked_write`]. pub fn jars_mut(&mut self) -> (&mut DB::Jars, &mut Runtime) { // Wait for all snapshots to be dropped. self.cancel_other_workers(); // Increment revision counter. self.runtime.new_revision(); // Acquire `&mut` access to `self.shared` -- this is only possible because // the snapshots have all been dropped, so we hold the only handle to the `Arc`. let jars = Arc::get_mut(self.shared.jars.as_mut().unwrap()).unwrap(); // Inform other ingredients that a new revision has begun. // This gives them a chance to free resources that were being held until the next revision. let routes = self.routes.clone(); for route in routes.reset_routes() { route(jars).reset_for_new_revision(); } // Return mut ref to jars + runtime. (jars, &mut self.runtime) } }
The key initial point is that it invokes cancel_other_workers before proceeding:
#![allow(unused)] fn main() { /// Sets cancellation flag and blocks until all other workers with access /// to this storage have completed. /// /// This could deadlock if there is a single worker with two handles to the /// same database! fn cancel_other_workers(&mut self) { loop { self.runtime.set_cancellation_flag(); // Acquire lock before we check if we have unique access to the jars. // If we do not yet have unique access, we will go to sleep and wait for // the snapshots to be dropped, which will signal the cond var associated // with this lock. // // NB: We have to acquire the lock first to ensure that we can check for // unique access and go to sleep waiting on the condvar atomically, // as described in PR #474. let mut guard = self.shared.noti_lock.lock(); // If we have unique access to the jars, we are done. if Arc::get_mut(self.shared.jars.as_mut().unwrap()).is_some() { return; } // Otherwise, wait until some other storage entities have dropped. // // The cvar `self.shared.cvar` is notified by the `Drop` impl. self.shared.cvar.wait(&mut guard); } } }
The Salsa runtime
The salsa runtime offers helper methods that are accessed by the ingredients.
It tracks, for example, the active query stack, and contains methods for adding dependencies between queries (e.g., report_tracked_read) or resolving cycles.
It also tracks the current revision and information about when values with low or high durability last changed.
Basically, the ingredient structures store the "data at rest" -- like memoized values -- and things that are "per ingredient".
The runtime stores the "active, in-progress" data, such as which queries are on the stack, and/or the dependencies accessed by the currently active query.
Tracked structs
Tracked structs are stored in a special way to reduce their costs.
Tracked structs are created via a new operation.
The tracked struct and tracked field ingredients
For a single tracked struct we create multiple ingredients.
The tracked struct ingredient is the ingredient created first.
It offers methods to create new instances of the struct and therefore
has unique access to the interner and hashtables used to create the struct id.
It also shares access to a hashtable that stores the TrackedStructValue that
contains the field data.
For each field, we create a tracked field ingredient that moderates access
to a particular field. All of these ingredients use that same shared hashtable
to access the TrackedStructValue instance for a given id. The TrackedStructValue
contains both the field values but also the revisions when they last changed value.
Each tracked struct has a globally unique id
This will begin by creating a globally unique, 32-bit id for the tracked struct. It is created by interning a combination of
- the currently executing query;
- a u64 hash of the
#[id]fields; - a disambiguator that makes this hash unique within the current query. i.e., when a query starts executing, it creates an empty map, and the first time a tracked struct with a given hash is created, it gets disambiguator 0. The next one will be given 1, etc.
Each tracked struct has a TrackedStructValue storing its data
The struct and field ingredients share access to a hashmap that maps each field id to a value struct:
#[derive(Debug)]
struct TrackedStructValue<C>
where
C: Configuration,
{
/// The durability minimum durability of all inputs consumed
/// by the creator query prior to creating this tracked struct.
/// If any of those inputs changes, then the creator query may
/// create this struct with different values.
durability: Durability,
/// The revision when this entity was most recently created.
/// Typically the current revision.
/// Used to detect "leaks" outside of the salsa system -- i.e.,
/// access to tracked structs that have not (yet?) been created in the
/// current revision. This should be impossible within salsa queries
/// but it can happen through "leaks" like thread-local data or storing
/// values outside of the root salsa query.
created_at: Revision,
/// Fields of this tracked struct. They can change across revisions,
/// but they do not change within a particular revision.
fields: C::Fields,
/// The revision information for each field: when did this field last change.
/// When tracked structs are re-created, this revision may be updated to the
/// current revision if the value is different.
revisions: C::Revisions,
}
The value struct stores the values of the fields but also the revisions when that field last changed. Each time the struct is recreated in a new revision, the old and new values for its fields are compared and a new revision is created.
The macro generates the tracked struct Configuration
The "configuration" for a tracked struct defines not only the types of the fields, but also various important operations such as extracting the hashable id fields and updating the "revisions" to track when a field last changed:
/// Trait that defines the key properties of a tracked struct.
/// Implemented by the `#[salsa::tracked]` macro when applied
/// to a struct.
pub trait Configuration {
/// The id type used to define instances of this struct.
/// The [`TrackedStructIngredient`][] contains the interner
/// that will create the id values.
type Id: InternedId;
/// A (possibly empty) tuple of the fields for this struct.
type Fields;
/// A array of [`Revision`][] values, one per each of the value fields.
/// When a struct is re-recreated in a new revision, the corresponding
/// entries for each field are updated to the new revision if their
/// values have changed (or if the field is marked as `#[no_eq]`).
type Revisions;
fn id_fields(fields: &Self::Fields) -> impl Hash;
/// Access the revision of a given value field.
/// `field_index` will be between 0 and the number of value fields.
fn revision(revisions: &Self::Revisions, field_index: u32) -> Revision;
/// Create a new value revision array where each element is set to `current_revision`.
fn new_revisions(current_revision: Revision) -> Self::Revisions;
/// Update an existing value revision array `revisions`,
/// given the tuple of the old values (`old_value`)
/// and the tuple of the values (`new_value`).
/// If a value has changed, then its element is
/// updated to `current_revision`.
fn update_revisions(
current_revision: Revision,
old_value: &Self::Fields,
new_value: &Self::Fields,
revisions: &mut Self::Revisions,
);
}
Query operations
Each of the query storage struct implements the QueryStorageOps trait found in the plumbing module:
pub trait QueryStorageOps<Q>
where
Self: QueryStorageMassOps,
Q: Query,
{
which defines the basic operations that all queries support. The most important are these two:
- maybe changed after: Returns true if the value of the query (for the given key) may have changed since the given revision.
- Fetch: Returns the up-to-date value for the given K (or an error in the case of an "unrecovered" cycle).
Maybe changed after
/// True if the value of `input`, which must be from this query, may have
/// changed after the given revision ended.
///
/// This function should only be invoked with a revision less than the current
/// revision.
fn maybe_changed_after(
&self,
db: &<Q as QueryDb<'_>>::DynDb,
input: DatabaseKeyIndex,
revision: Revision,
) -> bool;
The maybe_changed_after operation computes whether a query's value may have changed after the given revision. In other words, Q.maybe_change_since(R) is true if the value of the query Q may have changed in the revisions (R+1)..R_now, where R_now is the current revision. Note that it doesn't make sense to ask maybe_changed_after(R_now).
Input queries
Input queries are set explicitly by the user. maybe_changed_after can therefore just check when the value was last set and compare.
Interned queries
Derived queries
The logic for derived queries is more complex. We summarize the high-level ideas here, but you may find the flowchart useful to dig deeper. The terminology section may also be useful; in some cases, we link to that section on the first usage of a word.
- If an existing memo is found, then we check if the memo was verified in the current revision. If so, we can compare its changed at revision and return true or false appropriately.
- Otherwise, we must check whether dependencies have been modified:
- Let R be the revision in which the memo was last verified; we wish to know if any of the dependencies have changed since revision R.
- First, we check the durability. For each memo, we track the minimum durability of the memo's dependencies. If the memo has durability D, and there have been no changes to an input with durability D since the last time the memo was verified, then we can consider the memo verified without any further work.
- If the durability check is not sufficient, then we must check the dependencies individually. For this, we iterate over each dependency D and invoke the maybe changed after operation to check whether D has changed since the revision R.
- If no dependency was modified:
- We can mark the memo as verified and use its changed at revision to return true or false.
- Assuming dependencies have been modified:
- Then we execute the user's query function (same as in fetch), which potentially backdates the resulting value.
- Compare the changed at revision in the resulting memo and return true or false.
Fetch
/// Execute the query, returning the result (often, the result
/// will be memoized). This is the "main method" for
/// queries.
///
/// Returns `Err` in the event of a cycle, meaning that computing
/// the value for this `key` is recursively attempting to fetch
/// itself.
fn fetch(&self, db: &<Q as QueryDb<'_>>::DynDb, key: &Q::Key) -> Q::Value;
The fetch operation computes the value of a query. It prefers to reuse memoized values when it can.
Input queries
Input queries simply load the result from the table.
Interned queries
Interned queries map the input into a hashmap to find an existing integer. If none is present, a new value is created.
Derived queries
The logic for derived queries is more complex. We summarize the high-level ideas here, but you may find the flowchart useful to dig deeper. The terminology section may also be useful; in some cases, we link to that section on the first usage of a word.
- If an existing memo is found, then we check if the memo was verified in the current revision. If so, we can directly return the memoized value.
- Otherwise, if the memo contains a memoized value, we must check whether dependencies have been modified:
- Let R be the revision in which the memo was last verified; we wish to know if any of the dependencies have changed since revision R.
- First, we check the durability. For each memo, we track the minimum durability of the memo's dependencies. If the memo has durability D, and there have been no changes to an input with durability D since the last time the memo was verified, then we can consider the memo verified without any further work.
- If the durability check is not sufficient, then we must check the dependencies individually. For this, we iterate over each dependency D and invoke the maybe changed after operation to check whether D has changed since the revision R.
- If no dependency was modified:
- We can mark the memo as verified and return its memoized value.
- Assuming dependencies have been modified or the memo does not contain a memoized value:
- Then we execute the user's query function.
- Next, we compute the revision in which the memoized value last changed:
- Backdate: If there was a previous memoized value, and the new value is equal to that old value, then we can backdate the memo, which means to use the 'changed at' revision from before.
- Thanks to backdating, it is possible for a dependency of the query to have changed in some revision R1 but for the output of the query to have changed in some revision R2 where R2 predates R1.
- Otherwise, we use the current revision.
- Backdate: If there was a previous memoized value, and the new value is equal to that old value, then we can backdate the memo, which means to use the 'changed at' revision from before.
- Construct a memo for the new value and return it.
Derived queries flowchart
Derived queries are by far the most complex. This flowchart documents the flow of the maybe changed after and fetch operations. This flowchart can be edited on draw.io:
Cycles
Cross-thread blocking
The interface for blocking across threads now works as follows:
- When one thread
T1wishes to block on a queryQbeing executed by another threadT2, it invokesRuntime::try_block_on. This will check for cycles. Assuming no cycle is detected, it will blockT1untilT2has completed withQ. At that point,T1reawakens. However, we don't know the result of executingQ, soT1now has to "retry". Typically, this will result in successfully reading the cached value. - While
T1is blocking, the runtime moves its query stack (aVec) into the shared dependency graph data structure. WhenT1reawakens, it recovers ownership of its query stack before returning fromtry_block_on.
Cycle detection
When a thread T1 attempts to execute a query Q, it will try to load the value for Q from the memoization tables. If it finds an InProgress marker, that indicates that Q is currently being computed. This indicates a potential cycle. T1 will then try to block on the query Q:
- If
Qis also being computed byT1, then there is a cycle. - Otherwise, if
Qis being computed by some other threadT2, we have to check whetherT2is (transitively) blocked onT1. If so, there is a cycle.
These two cases are handled internally by the Runtime::try_block_on function. Detecting the intra-thread cycle case is easy; to detect cross-thread cycles, the runtime maintains a dependency DAG between threads (identified by RuntimeId). Before adding an edge T1 -> T2 (i.e., T1 is blocked waiting for T2) into the DAG, it checks whether a path exists from T2 to T1. If so, we have a cycle and the edge cannot be added (then the DAG would not longer be acyclic).
When a cycle is detected, the current thread T1 has full access to the query stacks that are participating in the cycle. Consider: naturally, T1 has access to its own stack. There is also a path T2 -> ... -> Tn -> T1 of blocked threads. Each of the blocked threads T2 ..= Tn will have moved their query stacks into the dependency graph, so those query stacks are available for inspection.
Using the available stacks, we can create a list of cycle participants Q0 ... Qn and store that into a Cycle struct. If none of the participants Q0 ... Qn have cycle recovery enabled, we panic with the Cycle struct, which will trigger all the queries on this thread to panic.
Cycle recovery via fallback
If any of the cycle participants Q0 ... Qn has cycle recovery set, we recover from the cycle. To help explain how this works, we will use this example cycle which contains three threads. Beginning with the current query, the cycle participants are QA3, QB2, QB3, QC2, QC3, and QA2.
The cyclic
edge we have
failed to add.
:
A : B C
:
QA1 v QB1 QC1
┌► QA2 ┌──► QB2 ┌─► QC2
│ QA3 ───┘ QB3 ──┘ QC3 ───┐
│ │
└───────────────────────────────┘
Recovery works in phases:
- Analyze: As we enumerate the query participants, we collect their collective inputs (all queries invoked so far by any cycle participant) and the max changed-at and min duration. We then remove the cycle participants themselves from this list of inputs, leaving only the queries external to the cycle.
- Mark: For each query Q that is annotated with
#[salsa::cycle], we mark it and all of its successors on the same thread by setting itscycleflag to thec: Cyclewe constructed earlier; we also reset its inputs to the collective inputs gathering during analysis. If those queries resume execution later, those marks will trigger them to immediately unwind and use cycle recovery, and the inputs will be used as the inputs to the recovery value.- Note that we mark all the successors of Q on the same thread, whether or not they have recovery set. We'll discuss later how this is important in the case where the active thread (A, here) doesn't have any recovery set.
- Unblock: Each blocked thread T that has a recovering query is forcibly reawoken; the outgoing edge from that thread to its successor in the cycle is removed. Its condvar is signalled with a
WaitResult::Cycle(c). When the thread reawakens, it will see that and start unwinding with the cyclec. - Handle the current thread: Finally, we have to choose how to have the current thread proceed. If the current thread includes any cycle with recovery information, then we can begin unwinding. Otherwise, the current thread simply continues as if there had been no cycle, and so the cyclic edge is added to the graph and the current thread blocks. This is possible because some other thread had recovery information and therefore has been awoken.
Let's walk through the process with a few examples.
Example 1: Recovery on the detecting thread
Consider the case where only the query QA2 has recovery set. It and QA3 will be marked with their cycle flag set to c: Cycle. Threads B and C will not be unblocked, as they do not have any cycle recovery nodes. The current thread (Thread A) will initiate unwinding with the cycle c as the value. Unwinding will pass through QA3 and be caught by QA2. QA2 will substitute the recovery value and return normally. QA1 and QC3 will then complete normally and so forth, on up until all queries have completed.
Example 2: Recovery in two queries on the detecting thread
Consider the case where both query QA2 and QA3 have recovery set. It proceeds the same Example 1 until the the current initiates unwinding, as described in Example 1. When QA3 receives the cycle, it stores its recovery value and completes normally. QA2 then adds QA3 as an input dependency: at that point, QA2 observes that it too has the cycle mark set, and so it initiates unwinding. The rest of QA2 therefore never executes. This unwinding is caught by QA2's entry point and it stores the recovery value and returns normally. QA1 and QC3 then continue normally, as they have not had their cycle flag set.
Example 3: Recovery on another thread
Now consider the case where only the query QB2 has recovery set. It and QB3 will be marked with the cycle c: Cycle and thread B will be unblocked; the edge QB3 -> QC2 will be removed from the dependency graph. Thread A will then add an edge QA3 -> QB2 and block on thread B. At that point, thread A releases the lock on the dependency graph, and so thread B is re-awoken. It observes the WaitResult::Cycle and initiates unwinding. Unwinding proceeds through QB3 and into QB2, which recovers. QB1 is then able to execute normally, as is QA3, and execution proceeds from there.
Example 4: Recovery on all queries
Now consider the case where all the queries have recovery set. In that case, they are all marked with the cycle, and all the cross-thread edges are removed from the graph. Each thread will independently awaken and initiate unwinding. Each query will recover.
Terminology
Backdate
Backdating is when we mark a value that was computed in revision R as having last changed in some earlier revision. This is done when we have an older memo M and we can compare the two values to see that, while the dependencies to M may have changed, the result of the query function did not.
Changed at
The changed at revision for a memo is the revision in which that memo's value last changed. Typically, this is the same as the revision in which the query function was last executed, but it may be an earlier revision if the memo was backdated.
Dependency
A dependency of a query Q is some other query Q1 that was invoked as part of computing the value for Q (typically, invoking by Q's query function).
Derived query
A derived query is a query whose value is defined by the result of a user-provided query function. That function is executed to get the result of the query. Unlike input queries, the result of a derived queries can always be recomputed whenever needed simply by re-executing the function.
Durability
Durability is an optimization that we use to avoid checking the dependencies of a query individually.
Input query
An input query is a query whose value is explicitly set by the user. When that value is set, a durability can also be provided.
Ingredient
An ingredient is an individual piece of storage used to create a salsa item See the jars and ingredients chapter for more details.
LRU
The set_lru_capacity method can be used to fix the maximum capacity for a query at a specific number of values. If more values are added after that point, then salsa will drop the values from older memos to conserve memory (we always retain the dependency information for those memos, however, so that we can still compute whether values may have changed, even if we don't know what that value is).
Memo
A memo stores information about the last time that a query function for some query Q was executed:
- Typically, it contains the value that was returned from that function, so that we don't have to execute it again.
- However, this is not always true: some queries don't cache their result values, and values can also be dropped as a result of LRU collection. In those cases, the memo just stores dependency information, which can still be useful to determine if other queries that have Q as a dependency may have changed.
- The revision in which the memo last verified.
- The changed at revision in which the memo's value last changed. (Note that it may be backdated.)
- The minimum durability of the memo's dependencies.
- The complete set of dependencies, if available, or a marker that the memo has an untracked dependency.
Query
Query function
The query function is the user-provided function that we execute to compute the value of a derived query. Salsa assumed that all query functions are a 'pure' function of their dependencies unless the user reports an untracked read. Salsa always assumes that functions have no important side-effects (i.e., that they don't send messages over the network whose results you wish to observe) and thus that it doesn't have to re-execute functions unless it needs their return value.
Revision
A revision is a monotonically increasing integer that we use to track the "version" of the database. Each time the value of an input query is modified, we create a new revision.
Salsa item
A salsa item is something that is decorated with a #[salsa::foo] macro, like a tracked function or struct.
See the jars and ingredients chapter for more details.
Salsa struct
A salsa struct is a struct decorated with one of the salsa macros:
#[salsa::tracked]#[salsa::input]#[salsa::interned]
See the salsa overview for more details.
Untracked dependency
An untracked dependency is an indication that the result of a derived query depends on something not visible to the salsa database. Untracked dependencies are created by invoking report_untracked_read or report_synthetic_read. When an untracked dependency is present, derived queries are always re-executed if the durability check fails (see the description of the fetch operation for more details).
Verified
A memo is verified in a revision R if we have checked that its value is still up-to-date (i.e., if we were to reexecute the query function, we are guaranteed to get the same result). Each memo tracks the revision in which it was last verified to avoid repeatedly checking whether dependencies have changed during the fetch and maybe changed after operations.
Meta: about the book itself
Linking policy
We try to avoid links that easily become fragile.
Do:
- Link to
docs.rstypes to document the public API, but modify the link to uselatestas the version. - Link to modules in the source code.
- Create "named anchors" and embed source code directly.
Don't:
- Link to direct lines on github, even within a specific commit, unless you are trying to reference a historical piece of code ("how things were at the time").