diff --git a/components/salsa-2022/src/function.rs b/components/salsa-2022/src/function.rs index cfadc8c4..9603f6df 100644 --- a/components/salsa-2022/src/function.rs +++ b/components/salsa-2022/src/function.rs @@ -30,15 +30,17 @@ mod store; mod sync; /// Function ingredients are the "workhorse" of salsa. -/// They are used for tracked functions, for the "value" fields of tracked structs, and for the fields of input structs. -/// The function ingredient is fairly complex and so its code is spread across multiple modules, typically one per method. -/// The main entry points are: +/// They are used for tracked functions, for the "value" fields of tracked structs, and for the +/// fields of input structs. The function ingredient is fairly complex and so its code is +/// spread across multiple modules, typically one per method. The main entry points are: /// -/// * the `fetch` method, which is invoked when the function is called by the user's code; -/// it will return a memoized value if one exists, or execute the function otherwise. -/// * the `specify` method, which can only be used when the key is an entity created by the active query. -/// It sets the value of the function imperatively, so that when later fetches occur, they'll return this value. -/// * the `store` method, which can only be invoked with an `&mut` reference, and is to set input fields. +/// * the `fetch` method, which is invoked when the function is called by the user's code; it +/// will return a memoized value if one exists, or execute the function otherwise. +/// * the `specify` method, which can only be used when the key is an entity created by the +/// active query. It sets the value of the function imperatively, so that when later fetches +/// occur, they'll return this value. +/// * the `store` method, which can only be invoked with an `&mut` reference, and is to set +/// input fields. pub struct FunctionIngredient { /// The ingredient index we were assigned in the database. /// Used to construct `DatabaseKeyIndex` values. @@ -95,8 +97,8 @@ pub trait Configuration { /// Invokes after a new result `new_value`` has been computed for which an older memoized /// value existed `old_value`. Returns true if the new value is equal to the older one - /// and hence should be "backdated" (i.e., marked as having last changed in an older revision, - /// even though it was recomputed). + /// and hence should be "backdated" (i.e., marked as having last changed in an older + /// revision, even though it was recomputed). /// /// This invokes user's code in form of the `Eq` impl. fn should_backdate_value(old_value: &Self::Value, new_value: &Self::Value) -> bool; @@ -183,8 +185,9 @@ where self.register(db); let memo = Arc::new(memo); let value = unsafe { - // Unsafety conditions: memo must be in the map (it's not yet, but it will be by the time this - // value is returned) and anything removed from map is added to deleted entries (ensured elsewhere). + // Unsafety conditions: memo must be in the map (it's not yet, but it will be by the + // time this value is returned) and anything removed from map is added to + // deleted entries (ensured elsewhere). self.extend_memo_lifetime(&memo) }; if let Some(old_value) = self.memo_map.insert(key, memo) { @@ -241,9 +244,10 @@ where _executor: DatabaseKeyIndex, _stale_output_key: Option, ) { - // This function is invoked when a query Q specifies the value for `stale_output_key` in rev 1, - // but not in rev 2. We don't do anything in this case, we just leave the (now stale) memo. - // Since its `verified_at` field has not changed, it will be considered dirty if it is invoked. + // This function is invoked when a query Q specifies the value for `stale_output_key` + // in rev 1, but not in rev 2. We don't do anything in this case, we just leave + // the (now stale) memo. Since its `verified_at` field has not changed, it will + // be considered dirty if it is invoked. } fn reset_for_new_revision(&mut self) { diff --git a/components/salsa-2022/src/ingredient.rs b/components/salsa-2022/src/ingredient.rs index 06b1a903..89ebb4cf 100644 --- a/components/salsa-2022/src/ingredient.rs +++ b/components/salsa-2022/src/ingredient.rs @@ -7,11 +7,13 @@ use super::Revision; /// "Ingredients" are the bits of data that are stored within the database to make salsa work. /// Each jar will define some number of ingredients that it requires. -/// Each use salsa macro (e.g., `#[salsa::tracked]`, `#[salsa::interned]`) adds one or more ingredients to the jar struct -/// that together are used to create the salsa concept. -/// For example, a tracked struct defines a [`crate::interned::InternedIngredient`] to store its identity -/// plus [`crate::function::FunctionIngredient`] values to store its fields. -/// The exact ingredients are determined by [`IngredientsFor`](`crate::storage::IngredientsFor`) implementations generated by the macro. +/// Each use salsa macro (e.g., `#[salsa::tracked]`, `#[salsa::interned]`) adds one or more +/// ingredients to the jar struct that together are used to create the salsa concept. +/// For example, a tracked struct defines a [`crate::interned::InternedIngredient`] to store +/// its identity plus [`crate::function::FunctionIngredient`] values to store its fields. +/// The exact ingredients are determined by +/// [`IngredientsFor`](`crate::storage::IngredientsFor`) implementations generated by the +/// macro. pub trait Ingredient { /// If this ingredient is a participant in a cycle, what is its cycle recovery strategy? /// (Really only relevant to [`crate::function::FunctionIngredient`], @@ -25,7 +27,8 @@ pub trait Ingredient { fn origin(&self, key_index: Id) -> Option; /// Invoked when the value `output_key` should be marked as valid in the current revision. - /// This occurs because the value for `executor`, which generated it, was marked as valid in the current revision. + /// This occurs because the value for `executor`, which generated it, was marked as valid + /// in the current revision. fn mark_validated_output(&self, db: &DB, executor: DatabaseKeyIndex, output_key: Option); /// Invoked when the value `stale_output` was output by `executor` in a previous @@ -46,11 +49,12 @@ pub trait Ingredient { fn salsa_struct_deleted(&self, db: &DB, id: Id); /// Invoked when a new revision is about to start. - /// This moment is important because it means that we have an `&mut`-reference to the database, - /// and hence any pre-existing `&`-references must have expired. + /// This moment is important because it means that we have an `&mut`-reference to the + /// database, and hence any pre-existing `&`-references must have expired. /// Many ingredients, given an `&'db`-reference to the database, /// use unsafe code to return `&'db`-references to internal values. - /// The backing memory for those values can only be freed once an `&mut`-reference to the database is created. + /// The backing memory for those values can only be freed once an `&mut`-reference to the + /// database is created. /// /// **Important:** to actually receive resets, the ingredient must set /// [`IngredientRequiresReset::RESET_ON_NEW_REVISION`] to true. @@ -58,7 +62,8 @@ pub trait Ingredient { } /// Defines a const indicating if an ingredient needs to be reset each round. -/// This const probably *should* be a member of `Ingredient` trait but then `Ingredient` would not be dyn-safe. +/// This const probably *should* be a member of `Ingredient` trait but then `Ingredient` would +/// not be dyn-safe. pub trait IngredientRequiresReset { /// If this is true, then `reset_for_new_revision` will be called every new revision. const RESET_ON_NEW_REVISION: bool;