rename Cache -> FactorInstancesCache and rename FIProvider outcomes

src/factor_instances_provider/provider/cache.rs → src/factor_instances_provider/provider/factor_instances_cache.rs

@@ -3,12 +3,12 @@ use std::ops::Add;
 use crate::prelude::*;
 
 #[derive(Debug, Default, Clone)]
-pub struct Cache {
-    /// PER FactorSource PER IndexAgnosticPath some value T
+pub struct FactorInstancesCache {
+    /// PER FactorSource PER IndexAgnosticPath FactorInstances (matching that IndexAgnosticPath)
     pub values: HashMap<FactorSourceIDFromHash, HashMap<IndexAgnosticPath, FactorInstances>>,
 }
 
-impl Cache {
+impl FactorInstancesCache {
     pub fn insert_for_factor(
         &mut self,
         factor_source_id: FactorSourceIDFromHash,
@@ -98,7 +98,7 @@ pub enum QuantityOutcome {
         instances: FactorInstances,
     },
 }
-impl Cache {
+impl FactorInstancesCache {
     fn __remove(
         &mut self,
         factor_source_id: &FactorSourceIDFromHash,
@@ -148,7 +148,7 @@ impl Cache {
 }
 
 #[cfg(test)]
-impl Cache {
+impl FactorInstancesCache {
     pub fn is_full(&self, network_id: NetworkID, factor_source_id: FactorSourceIDFromHash) -> bool {
         let count: usize = self
             .values

src/factor_instances_provider/provider/factor_instances_provider.rs

@@ -28,12 +28,12 @@ impl FactorInstancesProvider {
     /// Saves FactorInstances into the mutable `cache` parameter and returns a
     /// copy of the instances.
     pub async fn for_new_factor_source(
-        cache: &mut Cache,
+        cache: &mut FactorInstancesCache,
         profile: Option<Profile>,
         factor_source: HDFactorSource,
         network_id: NetworkID, // typically mainnet
         interactors: Arc<dyn KeysDerivationInteractors>,
-    ) -> Result<FactorInstancesProviderOutcomeForFactorFinal> {
+    ) -> Result<FactorInstancesProviderOutcomeForFactor> {
         // This is hacky! We are using `account_veci` as agnostic_path, we could
         // have used any other value... we are not going to use any instances directly
         // at all, why we specify `0` here, we piggyback on the rest of the logic
@@ -81,12 +81,12 @@ impl FactorInstancesProvider {
     /// We are always reading from the beginning of each FactorInstance collection in the cache,
     /// and we are always appending to the end.
     pub async fn for_account_veci(
-        cache: &mut Cache,
+        cache: &mut FactorInstancesCache,
         profile: Option<Profile>,
         factor_source: HDFactorSource,
         network_id: NetworkID,
         interactors: Arc<dyn KeysDerivationInteractors>,
-    ) -> Result<FactorInstancesProviderOutcomeForFactorFinal> {
+    ) -> Result<FactorInstancesProviderOutcomeForFactor> {
         let outcome = Self::with(
             network_id,
             cache,
@@ -124,12 +124,12 @@ impl FactorInstancesProvider {
     /// We are always reading from the beginning of each FactorInstance collection in the cache,
     /// and we are always appending to the end.
     pub async fn for_account_mfa(
-        cache: &mut Cache,
+        cache: &mut FactorInstancesCache,
         matrix_of_factor_sources: MatrixOfFactorSources,
         profile: Profile,
         accounts: IndexSet<AccountAddress>,
         interactors: Arc<dyn KeysDerivationInteractors>,
-    ) -> Result<FactorInstancesProviderOutcomeFinal> {
+    ) -> Result<FactorInstancesProviderOutcome> {
         let factor_sources_to_use = matrix_of_factor_sources.all_factors();
         let factor_sources = profile.factor_sources.clone();
         assert!(
@@ -185,15 +185,15 @@ impl FactorInstancesProvider {
 impl FactorInstancesProvider {
     async fn with(
         network_id: NetworkID,
-        cache: &mut Cache,
+        cache: &mut FactorInstancesCache,
         factor_sources: IndexSet<HDFactorSource>,
         index_agnostic_path_and_quantity_per_factor_source: IndexMap<
             FactorSourceIDFromHash,
             QuantifiedNetworkIndexAgnosticPath,
         >,
         next_index_assigner: &NextDerivationEntityIndexAssigner,
         interactors: Arc<dyn KeysDerivationInteractors>,
-    ) -> Result<FactorInstancesProviderOutcomeNonFinal> {
+    ) -> Result<InternalFactorInstancesProviderOutcome> {
         // clone cache so that we do not mutate the cache itself, later, if
         // derivation is successful, we will write back the changes made to
         // this cloned cache, on top of which we will save the newly derived
@@ -238,15 +238,15 @@ impl FactorInstancesProvider {
     #[allow(clippy::nonminimal_bool)]
     async fn with_copy_of_cache(
         network_id: NetworkID,
-        cache: &mut Cache,
+        cache: &mut FactorInstancesCache,
         factor_sources: IndexSet<HDFactorSource>,
         index_agnostic_path_and_quantity_per_factor_source: IndexMap<
             FactorSourceIDFromHash,
             QuantifiedNetworkIndexAgnosticPath,
         >,
         next_index_assigner: &NextDerivationEntityIndexAssigner,
         interactors: Arc<dyn KeysDerivationInteractors>,
-    ) -> Result<FactorInstancesProviderOutcomeNonFinal> {
+    ) -> Result<InternalFactorInstancesProviderOutcome> {
         // `pf` is short for `Per FactorSource`
         let mut pf_found_in_cache = IndexMap::<FactorSourceIDFromHash, FactorInstances>::new();
 
@@ -327,7 +327,7 @@ impl FactorInstancesProvider {
         }
 
         if !need_to_derive_more_instances {
-            return Ok(FactorInstancesProviderOutcomeNonFinal::satisfied_by_cache(
+            return Ok(InternalFactorInstancesProviderOutcome::satisfied_by_cache(
                 pf_found_in_cache,
             ));
         }
@@ -348,7 +348,7 @@ impl FactorInstancesProvider {
     #[allow(clippy::too_many_arguments)]
     async fn derive_more_instances(
         network_id: NetworkID,
-        cache: &mut Cache,
+        cache: &mut FactorInstancesCache,
         next_index_assigner: &NextDerivationEntityIndexAssigner,
         interactors: Arc<dyn KeysDerivationInteractors>,
         factor_sources: IndexSet<HDFactorSource>,
@@ -361,7 +361,7 @@ impl FactorInstancesProvider {
             QuantifiedNetworkIndexAgnosticPath,
         >,
         pf_found_in_cache: IndexMap<FactorSourceIDFromHash, FactorInstances>,
-    ) -> Result<FactorInstancesProviderOutcomeNonFinal> {
+    ) -> Result<InternalFactorInstancesProviderOutcome> {
         let mut pf_quantified_network_agnostic_paths_for_derivation = IndexMap::<
             FactorSourceIDFromHash,
             IndexSet<QuantifiedToCacheToUseNetworkIndexAgnosticPath>,
@@ -552,7 +552,7 @@ impl FactorInstancesProvider {
             }
         }
 
-        let outcome = FactorInstancesProviderOutcomeNonFinal::transpose(
+        let outcome = InternalFactorInstancesProviderOutcome::transpose(
             pf_to_cache,
             pf_to_use_directly
                 .into_iter()

src/factor_instances_provider/provider/factor_instances_provider_unit_tests.rs

@@ -82,7 +82,7 @@ async fn cache_is_always_filled_account_veci_then_after_all_used_we_start_over_a
 ) {
     let network = NetworkID::Mainnet;
     let bdfs = HDFactorSource::sample();
-    let mut cache = Cache::default();
+    let mut cache = FactorInstancesCache::default();
 
     let outcome = Sut::for_account_veci(
         &mut cache,

src/factor_instances_provider/provider/mod.rs

@@ -1,4 +1,4 @@
-mod cache;
+mod factor_instances_cache;
 mod factor_instances_provider;
 mod outcome;
 
@@ -7,6 +7,6 @@ mod factor_instances_provider_unit_tests;
 #[cfg(test)]
 mod test_sargon_os;
 
-pub use cache::*;
+pub use factor_instances_cache::*;
 pub use factor_instances_provider::*;
 pub use outcome::*;

src/factor_instances_provider/provider/outcome.rs

@@ -1,7 +1,13 @@
 use crate::prelude::*;
 
+/// Identical to `InternalFactorInstancesProviderOutcomeForFactor` but with
+/// different field names, making it clear that the instances of `to_cache` field in the
+/// "non-final" counterpart has already been cached, thus here named
+/// `debug_was_cached`.
+/// Furthermore all fields except `to_use_directly` are renamed to `debug_*` to make it clear they are only included for debugging purposes,
+/// in fact, they are all put behind `#[cfg(test)]`
 #[derive(Clone, Debug)]
-pub struct FactorInstancesProviderOutcomeForFactorFinal {
+pub struct FactorInstancesProviderOutcomeForFactor {
     #[allow(dead_code)]
     hidden: HiddenConstructor,
 
@@ -18,6 +24,7 @@ pub struct FactorInstancesProviderOutcomeForFactorFinal {
     /// Might be empty
     ///
     /// Useful for unit tests.
+    #[cfg(test)]
     pub debug_was_cached: FactorInstances,
 
     /// FactorInstances which was found in the cache before the operation was
@@ -28,6 +35,7 @@ pub struct FactorInstancesProviderOutcomeForFactorFinal {
     /// Useful for unit tests.
     ///
     /// Might overlap with `to_use_directly`
+    #[cfg(test)]
     pub debug_found_in_cache: FactorInstances,
 
     /// FactorInstances which was derived.
@@ -37,26 +45,37 @@ pub struct FactorInstancesProviderOutcomeForFactorFinal {
     /// Useful for unit tests.
     ///
     /// Might overlap with `to_cache` and `to_use_directly`
+    #[cfg(test)]
     pub debug_was_derived: FactorInstances,
 }
 
-impl From<FactorInstancesProviderOutcomeForFactorNonFinal>
-    for FactorInstancesProviderOutcomeForFactorFinal
+impl From<InternalFactorInstancesProviderOutcomeForFactor>
+    for FactorInstancesProviderOutcomeForFactor
 {
-    fn from(value: FactorInstancesProviderOutcomeForFactorNonFinal) -> Self {
-        Self {
+    fn from(value: InternalFactorInstancesProviderOutcomeForFactor) -> Self {
+        #[cfg(test)]
+        let _self = Self {
             hidden: HiddenConstructor,
             factor_source_id: value.factor_source_id,
             to_use_directly: value.to_use_directly,
             debug_was_cached: value.to_cache,
             debug_found_in_cache: value.found_in_cache,
             debug_was_derived: value.newly_derived,
-        }
+        };
+
+        #[cfg(not(test))]
+        let _self = Self {
+            hidden: HiddenConstructor,
+            factor_source_id: value.factor_source_id,
+            to_use_directly: value.to_use_directly,
+        };
+
+        _self
     }
 }
 
-impl From<FactorInstancesProviderOutcomeNonFinal> for FactorInstancesProviderOutcomeFinal {
-    fn from(value: FactorInstancesProviderOutcomeNonFinal) -> Self {
+impl From<InternalFactorInstancesProviderOutcome> for FactorInstancesProviderOutcome {
+    fn from(value: InternalFactorInstancesProviderOutcome) -> Self {
         Self {
             per_factor: value
                 .per_factor
@@ -68,7 +87,7 @@ impl From<FactorInstancesProviderOutcomeNonFinal> for FactorInstancesProviderOut
 }
 
 #[derive(Clone, Debug)]
-pub struct FactorInstancesProviderOutcomeForFactorNonFinal {
+pub struct InternalFactorInstancesProviderOutcomeForFactor {
     #[allow(dead_code)]
     hidden: HiddenConstructor,
 
@@ -104,7 +123,7 @@ pub struct FactorInstancesProviderOutcomeForFactorNonFinal {
     /// Might overlap with `to_cache` and `to_use_directly`
     pub newly_derived: FactorInstances,
 }
-impl FactorInstancesProviderOutcomeForFactorNonFinal {
+impl InternalFactorInstancesProviderOutcomeForFactor {
     pub fn new(
         factor_source_id: FactorSourceIDFromHash,
         to_cache: FactorInstances,
@@ -157,13 +176,15 @@ impl FactorInstancesProviderOutcomeForFactorNonFinal {
     }
 }
 
+/// Identical to `FactorInstancesProviderOutcome` but `FactorInstancesProviderOutcomeForFactor` instead of `InternalFactorInstancesProviderOutcomeForFactor`, having
+/// renamed field values to make it clear that `to_cache` instances  already have been cached.
 #[derive(Clone, Debug)]
-pub struct FactorInstancesProviderOutcomeFinal {
-    pub per_factor: IndexMap<FactorSourceIDFromHash, FactorInstancesProviderOutcomeForFactorFinal>,
+pub struct FactorInstancesProviderOutcome {
+    pub per_factor: IndexMap<FactorSourceIDFromHash, FactorInstancesProviderOutcomeForFactor>,
 }
 
 #[cfg(test)]
-impl FactorInstancesProviderOutcomeFinal {
+impl FactorInstancesProviderOutcome {
     pub fn newly_derived_instances_from_all_factor_sources(&self) -> FactorInstances {
         self.per_factor
             .values()
@@ -197,20 +218,22 @@ impl FactorInstancesProviderOutcomeFinal {
 }
 
 #[derive(Clone, Debug)]
-pub struct FactorInstancesProviderOutcomeNonFinal {
+pub struct InternalFactorInstancesProviderOutcome {
     pub per_factor:
-        IndexMap<FactorSourceIDFromHash, FactorInstancesProviderOutcomeForFactorNonFinal>,
+        IndexMap<FactorSourceIDFromHash, InternalFactorInstancesProviderOutcomeForFactor>,
 }
 
-impl FactorInstancesProviderOutcomeNonFinal {
+impl InternalFactorInstancesProviderOutcome {
     pub fn new(
         per_factor: IndexMap<
             FactorSourceIDFromHash,
-            FactorInstancesProviderOutcomeForFactorNonFinal,
+            InternalFactorInstancesProviderOutcomeForFactor,
         >,
     ) -> Self {
         Self { per_factor }
     }
+
+    /// Outcome of FactorInstances just from cache, none have been derived.
     pub fn satisfied_by_cache(
         pf_found_in_cache: IndexMap<FactorSourceIDFromHash, FactorInstances>,
     ) -> Self {
@@ -220,12 +243,14 @@ impl FactorInstancesProviderOutcomeNonFinal {
                 .map(|(k, v)| {
                     (
                         k,
-                        FactorInstancesProviderOutcomeForFactorNonFinal::satisfied_by_cache(k, v),
+                        InternalFactorInstancesProviderOutcomeForFactor::satisfied_by_cache(k, v),
                     )
                 })
                 .collect(),
         )
     }
+
+    /// "Transposes" a **collection** of `IndexMap<FactorSourceID, FactorInstances>` into `IndexMap<FactorSourceID, **collection** FactorInstances>` (`InternalFactorInstancesProviderOutcomeForFactor` is essentially a collection of FactorInstance)
     pub fn transpose(
         pf_to_cache: IndexMap<FactorSourceIDFromHash, FactorInstances>,
         pf_to_use_directly: IndexMap<FactorSourceIDFromHash, FactorInstances>,
@@ -247,12 +272,12 @@ impl FactorInstancesProviderOutcomeNonFinal {
             pub newly_derived: IndexSet<HierarchicalDeterministicFactorInstance>,
         }
         impl Builder {
-            fn build(self) -> FactorInstancesProviderOutcomeForFactorNonFinal {
+            fn build(self) -> InternalFactorInstancesProviderOutcomeForFactor {
                 let to_cache = FactorInstances::from(self.to_cache);
                 let to_use_directly = FactorInstances::from(self.to_use_directly);
                 let found_in_cache = FactorInstances::from(self.found_in_cache);
                 let newly_derived = FactorInstances::from(self.newly_derived);
-                FactorInstancesProviderOutcomeForFactorNonFinal::new(
+                InternalFactorInstancesProviderOutcomeForFactor::new(
                     self.factor_source_id,
                     to_cache,
                     to_use_directly,
@@ -316,7 +341,7 @@ impl FactorInstancesProviderOutcomeNonFinal {
             builders
                 .into_iter()
                 .map(|(k, v)| (k, v.build()))
-                .collect::<IndexMap<FactorSourceIDFromHash, FactorInstancesProviderOutcomeForFactorNonFinal>>(),
+                .collect::<IndexMap<FactorSourceIDFromHash, InternalFactorInstancesProviderOutcomeForFactor>>(),
         )
     }
 }