From 2ea6759b0f4fb0709d1536225d366a0c114ec8a7 Mon Sep 17 00:00:00 2001 From: Carl Meyer Date: Wed, 24 Jul 2024 20:32:22 -0700 Subject: [PATCH 1/3] [book] fix the cycle fallback section to match current code --- book/src/cycles/fallback.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/book/src/cycles/fallback.md b/book/src/cycles/fallback.md index 128947b47..e2d821af2 100644 --- a/book/src/cycles/fallback.md +++ b/book/src/cycles/fallback.md @@ -2,17 +2,16 @@ 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 input ingredient to the query that caused the cycle; it returns the result of the query. Example: ```rust fn my_recover_fn( db: &dyn MyDatabase, cycle: &salsa::Cycle, + input: MyIngredient, ) -> 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. From 8e2a784b8e3e7c8c51207f666fe50e2616f53e6a Mon Sep 17 00:00:00 2001 From: Carl Meyer Date: Mon, 29 Jul 2024 09:15:47 -0700 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Niko Matsakis --- book/src/cycles/fallback.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/book/src/cycles/fallback.md b/book/src/cycles/fallback.md index e2d821af2..250901717 100644 --- a/book/src/cycles/fallback.md +++ b/book/src/cycles/fallback.md @@ -4,13 +4,15 @@ Panicking when a cycle occurs is ok for situations where you believe a cycle is 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 and the input ingredient to the query that caused the cycle; 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 fn my_recover_fn( db: &dyn MyDatabase, cycle: &salsa::Cycle, - input: MyIngredient, + arg1: T1, + ... + argN: TN, ) -> MyResultValue ``` From 148abe38f6e8a12349d39d74b80cfe819312ba60 Mon Sep 17 00:00:00 2001 From: Carl Meyer Date: Mon, 29 Jul 2024 09:28:37 -0700 Subject: [PATCH 3/3] Add link to example in tests --- book/src/cycles/fallback.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/book/src/cycles/fallback.md b/book/src/cycles/fallback.md index 250901717..d3971ece5 100644 --- a/book/src/cycles/fallback.md +++ b/book/src/cycles/fallback.md @@ -16,4 +16,6 @@ fn my_recover_fn( ) -> MyResultValue ``` +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.