mirrors/salsa
1
0
Fork 0
mirror of https://github.com/salsa-rs/salsa.git synced 2025-01-23 05:07:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Merge pull request #528 from carljm/fix-book-cycle-fallback
Some checks failed
Book / Book (push) Has been cancelled
Details
Test / Test (false, beta) (push) Has been cancelled
Details
Test / Test (false, stable) (push) Has been cancelled
Details
Test / Test (true, nightly) (push) Has been cancelled
Details
Test / Miri (push) Has been cancelled
Details
Test / Benchmarks (push) Has been cancelled
Details
Book / Deploy (push) Has been cancelled
Details

Browse source 
[book] fix the cycle fallback section to match current code
This commit is contained in:
Niko Matsakis 2024-08-07 06:06:33 +00:00 committed by GitHub
commit 05c7fbea45
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 6 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
book/src/cycles/fallback.md
View file

@ -2,17 +2,20 @@
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*. 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. To use cycle recovery, you annotate potential participants in the cycle with the `recovery_fn` argument to `#[salsa::tracked]`, e.g. `#[salsa::tracked(recovery_fn=my_recovery_fn)]`. 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: 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 and the arguments to the tracked function that caused the cycle; it returns the result of the query. Example:
```rust ```rust
fn my_recover_fn( fn my_recover_fn(
db: &dyn MyDatabase, db: &dyn MyDatabase,
cycle: &salsa::Cycle, cycle: &salsa::Cycle,
arg1: T1,
...
argN: TN,
) -> MyResultValue ) -> MyResultValue
``` ```
The `db` and `cycle` argument can be used to prepare a useful error message for your users. See [the tests](https://github.com/salsa-rs/salsa/blob/cd339fc1c9a6ea0ffb1d09bd3bffb5633f776ef3/tests/cycles.rs#L132-L141) for an example.
**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. **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.