Document how to tune Salsa

book/src/SUMMARY.md

@@ -8,6 +8,7 @@
 - [Common patterns](./common_patterns.md)
   - [Selection](./common_patterns/selection.md)
   - [On-demand (Lazy) inputs](./common_patterns/on_demand_inputs.md)
+- [Tuning](./tuning.md)
 - [Cycle handling](./cycles.md)
   - [Recovering via fallback](./cycles/fallback.md)
 

book/src/rfcs/RFC0007-Opinionated-Cancelation.md

@@ -28,7 +28,7 @@ We propose to make this model of cancelation the *only* model of cancelation.
 
 ## User's guide
 
-When you do a write to the salsa database, that write will block until any queries running in background threads have completed. You really want those queries to complete quickly, though, because they are now operating on stale data and their results are therefore not meaningful. To expedite the process, salsa will *cancel* those queries. That means that the queries will panic as soon as they try to execute another salsa query. Those panics occur using a sentinel value that you can check for if you wish. 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 cancelation yourself by invoking the `unwind_if_canceled` method.
+When you do a write to the salsa database, that write will block until any queries running in background threads have completed. You really want those queries to complete quickly, though, because they are now operating on stale data and their results are therefore not meaningful. To expedite the process, salsa will *cancel* those queries. That means that the queries will panic as soon as they try to execute another salsa query. Those panics occur using a sentinel value that you can check for if you wish. 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 cancelation yourself by invoking the `unwind_if_cancelled` method.
 
 ## Reference guide
 
@@ -36,10 +36,10 @@ The changes required to implement this RFC are as follows:
 
 * Remove on `is_current_revision_canceled`.
 * Introduce a sentinel cancellation token that can be used with [`resume_unwind`](https://doc.rust-lang.org/std/panic/fn.resume_unwind.html)
-* Introduce a `unwind_if_canceled` method into the `Database` which checks whether cancelation has occured and panics if so.
+* Introduce a `unwind_if_cancelled` method into the `Database` which checks whether cancelation has occured and panics if so.
     * This method also triggers a `salsa_event` callback.
     * This should probably be inline for the `if` with an outlined function to do the actual panic.
-* Modify the code for the various queries to invoke `unwind_if_canceled` when they are invoked or validated.
+* Modify the code for the various queries to invoke `unwind_if_cancelled` when they are invoked or validated.
 
 ## Frequently asked questions
 

book/src/tuning.md

@@ -0,0 +1,53 @@
+# Tuning Salsa
+
+## LRU Cache
+
+You can specify an LRU cache size for any non-input query:
+
+```rs
+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.
+
+See [The LRU RFC for more details](./rfcs/RFC0004-LRU.md).
+
+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`](https://doc.rust-lang.org/std/sync/struct.Arc.html).
+
+Interning is especially useful for queries that involve nested,
+tree-like data structures.
+
+See:
+- The [Intern Queries RFC](./rfcs/RFC0002-Intern-Queries.md)
+- The [`compiler` example](https://github.com/salsa-rs/salsa/blob/master/examples/compiler/main.rs),
+which uses interning.
+
+## Granularity of Incrementality
+
+See:
+- [common patterns: selection](./common_patterns/selection.md) and
+- The [`selection` example](https://github.com/salsa-rs/salsa/blob/master/examples/selection/main.rs)
+
+## Cancellation
+
+Queries that are no longer needed due to concurrent writes or changes in dependencies are cancelled
+by Salsa. Each accesss 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 Opinionated cancellation RFC](./rfcs/RFC0007-Opinionated-Cancelation.md).
+- The tests for cancellation behavior in the Salsa repo.
+