diff --git a/overview.html b/overview.html index 3ae9dc8d..de9858d3 100644 --- a/overview.html +++ b/overview.html @@ -198,17 +198,18 @@ pub struct ProgramFile { }

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:

+Because the values of input fields are stored in the database, you also give an &-reference to the database:


 #![allow(unused)]
 fn main() {
 let file: ProgramFile = ProgramFile::new(
-    &mut db,
+    &db,
     PathBuf::from("some_path.txt"),
     String::from("fn foo() { }"),
 );
 }
 
+

Mutable access is not needed since creating a new input cannot affect existing tracked data in the database.

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:


@@ -253,7 +254,8 @@ pub struct ProgramFile {
 

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:

+Since this is modifying the input, and potentially invalidating data derived from it, +the setter takes an &mut-reference to the database:


 #![allow(unused)]
 fn main() {
@@ -282,7 +284,7 @@ The algorithm Salsa uses to decide when a tracked function needs to be re-execut
 

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:

+Because the values of input fields are stored in the database, you also give an &-reference to the database:


 #![allow(unused)]
 fn main() {
 let file: ProgramFile = ProgramFile::new(
-    &mut db,
+    &db,
     PathBuf::from("some_path.txt"),
     String::from("fn foo() { }"),
 );
 }
 
+

Mutable access is not needed since creating a new input cannot affect existing tracked data in the database.

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:


@@ -270,7 +271,8 @@ pub struct ProgramFile {
 

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:

+Since this is modifying the input, and potentially invalidating data derived from it, +the setter takes an &mut-reference to the database:


 #![allow(unused)]
 fn main() {
@@ -299,7 +301,7 @@ The algorithm Salsa uses to decide when a tracked function needs to be re-execut
 

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:

+For an input, a &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());
+let source = SourceProgram::new(&db, "print 11 + 11".to_string());
 }
 

You can read the value of the field with source.text(&db), @@ -799,7 +801,7 @@ 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: