Apache DataFusion SQL Query Engine
Make StatisticsContext cache entries node-lifetime safe (#25929)
kosiew416002a5b908
diff --git a/datafusion/physical-optimizer/src/ensure_requirements/enforce_distribution.rs b/datafusion/physical-optimizer/src/ensure_requirements/enforce_distribution.rsindex 87b93573f4..3c2426a5ef 100644--- a/datafusion/physical-optimizer/src/ensure_requirements/enforce_distribution.rs+++ b/datafusion/physical-optimizer/src/ensure_requirements/enforce_distribution.rs@@ -1010,7 +1010,7 @@ fn get_repartition_requirement_status(// Decide whether adding a round robin is beneficial depending on// the statistical information we have on the number of rows:let roundrobin_beneficial_stats = match stats_ctx- .compute(child.as_ref(), &StatisticsArgs::new())?+ .compute_arc(child, &StatisticsArgs::new())?.num_rows{Precision::Exact(n_rows) => n_rows > batch_size,@@ -1353,9 +1353,7 @@ pub fn ensure_distribution(/// `stats_ctx` carries the memoization cache used to answer the child/// statistics queries behind the repartition decisions. Share one context/// across the whole traversal so each subtree is computed once rather than-/// once per ancestor. The cache is keyed by raw plan-node pointers, so reset-/// it (via [`StatisticsContext::reset_cache`]) after any node whose plan-/// pointer actually changed.+/// once per ancestor.#[expect(deprecated,reason = "HashPartitioned is accepted during the KeyPartitioned migration"diff --git a/datafusion/physical-optimizer/src/ensure_requirements/mod.rs b/datafusion/physical-optimizer/src/ensure_requirements/mod.rsindex 08e708baa5..3909b56c17 100644--- a/datafusion/physical-optimizer/src/ensure_requirements/mod.rs+++ b/datafusion/physical-optimizer/src/ensure_requirements/mod.rs@@ -225,24 +225,12 @@ impl PhysicalOptimizerRule for EnsureRequirements {// subtree's statistics are computed once instead of once per ancestor.// Build it from the session's statistics registry so registered providers// are consulted (an empty registry, the default, is unchanged behavior).- // `StatsCache` is keyed by raw node pointer, so reset it after any node- // whose plan pointer actually changed: a rewrite can free a cached node- // and a later allocation could reuse its address. A node that makes no- // change cannot free anything, so the cache safely persists across the- // no-op nodes that dominate a deep plan.let stats_ctx = match context.statistics_registry() {Some(registry) => StatisticsContext::new_with_registry(registry.clone()),None => StatisticsContext::new(),};let dist_ctx = dist_ctx- .transform_up(|ctx| {- let before = Arc::clone(&ctx.plan);- let result = ensure_distribution_with_stats(ctx, config, &stats_ctx)?;- if !Arc::ptr_eq(&before, &result.data.plan) {- stats_ctx.reset_cache();- }- Ok(result)- })+ .transform_up(|ctx| ensure_distribution_with_stats(ctx, config, &stats_ctx)).data()?;// Step 2b: Sorting enforcement (bottom-up) — runs on distribution-fixed plandiff --git a/datafusion/physical-plan/src/statistics.rs b/datafusion/physical-plan/src/statistics.rsindex 881638fa6e..603a8e40a1 100644--- a/datafusion/physical-plan/src/statistics.rs+++ b/datafusion/physical-plan/src/statistics.rs@@ -45,23 +45,26 @@ fn cache_key(plan: &dyn ExecutionPlan, partition: Option<usize>) -> CacheKey {)}-/// Per-call memoization cache for statistics computation.+/// Per-context memoization cache for statistics computation.///-/// Keyed by `(plan node pointer address, partition)`. Shared across-/// a single statistics walk via [`StatisticsContext`].-///-/// The pointer-based key is safe within a single synchronous walk:-/// all `Arc<dyn ExecutionPlan>` nodes are held by the plan tree for-/// the duration of the walk, so addresses cannot be reused.+/// Keys are `(plan node pointer address, partition)`. Every entry retains the+/// `Arc` whose pointer supplied its key, preventing a dropped plan's address+/// from being reused by a different plan while the entry exists.////// Core statistics and provider extensions are cached separately: the/// `statistics` map is the hot path (populated on every walk); the `extensions`/// map is populated only when a provider returns non-empty extensions, so a walk/// with no providers never touches it.+#[derive(Debug)]+struct CacheEntry<T> {+ _plan: Arc<dyn ExecutionPlan>,+ value: T,+}+#[derive(Debug, Default)]struct StatsCache {- statistics: HashMap<CacheKey, Arc<Statistics>>,- extensions: HashMap<CacheKey, Extensions>,+ statistics: HashMap<CacheKey, CacheEntry<Arc<Statistics>>>,+ extensions: HashMap<CacheKey, CacheEntry<Extensions>>,}/// Arguments passed to [`ExecutionPlan::statistics_from_inputs`] carrying@@ -113,9 +116,15 @@ pub enum ChildStats {Skip,}-/// Owns the bottom-up traversal and per-walk memoization cache for statistics+/// Owns the bottom-up traversal and memoization cache for statistics/// computation. Call [`StatisticsContext::compute`] to walk a plan tree.///+/// The cache lives as long as the context and may be shared across walks and+/// plan rewrites. Each entry holds a strong reference to the plan node it was+/// computed for, so cached nodes (and their per-partition statistics) stay+/// alive until [`Self::reset_cache`] is called or the context is dropped. Reset+/// a long-lived context at a lifecycle boundary to bound its memory.+////// An optional [`StatisticsRegistry`] plugs providers into the walk: at each node/// they are consulted before the operator's built-in/// [`ExecutionPlan::statistics_from_inputs`]. An empty registry is the built-in@@ -153,12 +162,11 @@ impl StatisticsContext {}}- /// Clears the memoization cache.+ /// Clears the memoization cache and releases its retained plan nodes.///- /// The cache is keyed by raw plan-node pointers, which are only stable- /// while the current plan tree is alive. Reset between optimizer passes- /// (which rewrite the plan) when reusing one context across them, so stale- /// pointer keys cannot collide.+ /// Resetting is optional for correctness: each cache entry retains the plan+ /// node that supplied its pointer key. Use it to bound memory at a logical+ /// lifecycle boundary, such as after an optimizer pass.pub fn reset_cache(&self) {let mut cache = self.cache.borrow_mut();cache.statistics.clear();@@ -168,6 +176,15 @@ impl StatisticsContext {/// Computes the core [`Statistics`] for `plan`, discarding any/// provider-supplied extensions (see [`Self::compute_extended`]).///+ /// The root's own statistics are not memoized, because a borrowed plan+ /// cannot be retained by the cache; its descendants are. Use+ /// [`Self::compute_arc`] to also memoize the root.+ ///+ /// A borrowed root is still looked up in the cache by address, so it must+ /// be a standalone plan node (normally the pointee of an+ /// `Arc<dyn ExecutionPlan>`), not a plan stored inline within another+ /// cached node.+ ////// With no providers registered this is the plain built-in walk: only the/// `statistics` cache is touched, so it carries no extension overhead.///@@ -207,19 +224,80 @@ impl StatisticsContext {plan: &dyn ExecutionPlan,args: &StatisticsArgs,) -> Result<Arc<Statistics>> {- self.compute_base(plan, args, false)+ self.compute_base(plan, None, args, false)+ .map(|(statistics, _)| statistics)+ }++ /// Like [`Self::compute`], but the cache retains `plan` so the root's own+ /// statistics are memoized as well as its descendants'.+ ///+ /// Prefer this when sharing one context across repeated calls on the same+ /// nodes, such as an optimizer pass.+ ///+ /// # Example+ ///+ /// ```+ /// # use std::sync::Arc;+ /// # use arrow::datatypes::{DataType, Field, Schema};+ /// # use datafusion_common::Statistics;+ /// # use datafusion_common::stats::Precision;+ /// # use datafusion_physical_plan::ExecutionPlan;+ /// # use datafusion_physical_plan::statistics::{StatisticsArgs, StatisticsContext};+ /// # use datafusion_physical_plan::test::exec::StatisticsExec;+ ///+ /// let schema = Schema::new(vec![Field::new("a", DataType::Int32, false)]);+ /// let stats = Statistics::new_unknown(&schema).with_num_rows(Precision::Exact(100));+ /// let plan: Arc<dyn ExecutionPlan> = Arc::new(StatisticsExec::new(stats, schema));+ ///+ /// let context = StatisticsContext::new();+ /// let first = context.compute_arc(&plan, &StatisticsArgs::new())?;+ /// let second = context.compute_arc(&plan, &StatisticsArgs::new())?;+ ///+ /// // The second call is a cache hit for the root.+ /// assert!(Arc::ptr_eq(&first, &second));+ /// assert_eq!(first.num_rows, Precision::Exact(100));+ /// # Ok::<(), datafusion_common::DataFusionError>(())+ /// ```+ pub fn compute_arc(+ &self,+ plan: &Arc<dyn ExecutionPlan>,+ args: &StatisticsArgs,+ ) -> Result<Arc<Statistics>> {+ self.compute_base(plan.as_ref(), Some(plan), args, false).map(|(statistics, _)| statistics)}/// Computes the [`ExtendedStatistics`] for `plan`: the core statistics plus/// any extensions a provider attached to this node (see the type-level docs- /// for how extensions propagate up the tree).+ /// for how extensions propagate up the tree). As with [`Self::compute`],+ /// the root is not memoized and must be a standalone plan node; see+ /// [`Self::compute_extended_arc`].pub fn compute_extended(&self,plan: &dyn ExecutionPlan,args: &StatisticsArgs,) -> Result<Arc<ExtendedStatistics>> {- let (statistics, extensions) = self.compute_base(plan, args, true)?;+ self.compute_extended_base(plan, None, args)+ }++ /// Like [`Self::compute_extended`], but the cache retains `plan` so the+ /// root's own statistics and extensions are memoized as well.+ pub fn compute_extended_arc(+ &self,+ plan: &Arc<dyn ExecutionPlan>,+ args: &StatisticsArgs,+ ) -> Result<Arc<ExtendedStatistics>> {+ self.compute_extended_base(plan.as_ref(), Some(plan), args)+ }++ fn compute_extended_base(+ &self,+ plan: &dyn ExecutionPlan,+ retained_plan: Option<&Arc<dyn ExecutionPlan>>,+ args: &StatisticsArgs,+ ) -> Result<Arc<ExtendedStatistics>> {+ let (statistics, extensions) =+ self.compute_base(plan, retained_plan, args, true)?;Ok(Arc::new(ExtendedStatistics::new_with_extensions(statistics,extensions.unwrap_or_default(),@@ -243,6 +321,7 @@ impl StatisticsContext {fn compute_base(&self,plan: &dyn ExecutionPlan,+ retained_plan: Option<&Arc<dyn ExecutionPlan>>,args: &StatisticsArgs,read_cached_extensions: bool,) -> Result<(Arc<Statistics>, Option<Extensions>)> {@@ -274,7 +353,7 @@ impl StatisticsContext {// Try providers before resolving the operator's own children, so a// provider that overrides this node is not blocked by the fallback walk.let (statistics, extensions) =- match self.try_provider_stats(plan, &children, args)? {+ match self.try_provider_stats(plan, retained_plan, &children, args)? {Some(computed) => computed,None => {let requests = plan.child_stats_requests(partition);@@ -284,7 +363,9 @@ impl StatisticsContext {(plan.statistics_from_inputs(&child_statistics, args)?, None)}};- self.store_statistics(plan, partition, Arc::clone(&statistics));+ if let Some(owner) = retained_plan {+ self.store_statistics(owner, partition, Arc::clone(&statistics));+ }Ok((statistics, extensions))}@@ -336,6 +417,7 @@ impl StatisticsContext {ChildStats::At(p) => self.compute_base(child.as_ref(),+ Some(child),&StatisticsArgs::new().with_partition(*p),false,)@@ -366,6 +448,7 @@ impl StatisticsContext {fn try_provider_stats(&self,plan: &dyn ExecutionPlan,+ retained_plan: Option<&Arc<dyn ExecutionPlan>>,children: &[&Arc<dyn ExecutionPlan>],args: &StatisticsArgs,) -> Result<Option<(Arc<Statistics>, Option<Extensions>)>> {@@ -405,7 +488,9 @@ impl StatisticsContext {let extensions = if extensions.is_empty() {None} else {- self.store_extensions(plan, partition, extensions.clone());+ if let Some(owner) = retained_plan {+ self.store_extensions(owner, partition, extensions.clone());+ }Some(extensions)};return Ok(Some((statistics, extensions)));@@ -452,19 +537,38 @@ impl StatisticsContext {.borrow().statistics.get(&cache_key(plan, partition))- .cloned()+ .map(|entry| Arc::clone(&entry.value))+ }++ /// Inserts `value` keyed by `owner`'s pointer, retaining `owner` so the+ /// key's address cannot be reused while the entry exists.+ fn store_cache_entry<T>(+ cache: &mut HashMap<CacheKey, CacheEntry<T>>,+ owner: &Arc<dyn ExecutionPlan>,+ partition: Option<usize>,+ value: T,+ ) {+ cache.insert(+ cache_key(owner.as_ref(), partition),+ CacheEntry {+ _plan: Arc::clone(owner),+ value,+ },+ );}fn store_statistics(&self,- plan: &dyn ExecutionPlan,+ owner: &Arc<dyn ExecutionPlan>,partition: Option<usize>,statistics: Arc<Statistics>,) {- self.cache- .borrow_mut()- .statistics- .insert(cache_key(plan, partition), statistics);+ Self::store_cache_entry(+ &mut self.cache.borrow_mut().statistics,+ owner,+ partition,+ statistics,+ );}fn cached_extensions(@@ -476,19 +580,21 @@ impl StatisticsContext {.borrow().extensions.get(&cache_key(plan, partition))- .cloned()+ .map(|entry| entry.value.clone())}fn store_extensions(&self,- plan: &dyn ExecutionPlan,+ owner: &Arc<dyn ExecutionPlan>,partition: Option<usize>,extensions: Extensions,) {- self.cache- .borrow_mut()- .extensions- .insert(cache_key(plan, partition), extensions);+ Self::store_cache_entry(+ &mut self.cache.borrow_mut().extensions,+ owner,+ partition,+ extensions,+ );}}@@ -631,18 +737,126 @@ mod tests {let ctx = StatisticsContext::new();let args = StatisticsArgs::new();- let s1 = ctx.compute(leaf.as_ref(), &args).unwrap();+ let s1 = ctx.compute_arc(&leaf, &args).unwrap();assert!(!ctx.cache.borrow().statistics.is_empty());- let s2 = ctx.compute(leaf.as_ref(), &args).unwrap();+ let s2 = ctx.compute_arc(&leaf, &args).unwrap();assert!(Arc::ptr_eq(&s1, &s2));}+ #[test]+ fn context_cache_retains_plan_lifetime() {+ let leaf = make_stats_leaf(10);+ let weak = Arc::downgrade(&leaf);+ let ctx = StatisticsContext::new();++ let _ = ctx.compute_arc(&leaf, &StatisticsArgs::new()).unwrap();+ drop(leaf);+ assert!(weak.upgrade().is_some());++ ctx.reset_cache();+ assert!(weak.upgrade().is_none());+ }++ #[test]+ fn owned_parent_and_leaf_are_released_by_reset() {+ let leaf = make_stats_leaf(10);+ let leaf_weak = Arc::downgrade(&leaf);+ let parent: Arc<dyn ExecutionPlan> =+ Arc::new(CoalescePartitionsExec::new(Arc::clone(&leaf)));+ let parent_weak = Arc::downgrade(&parent);+ let ctx = StatisticsContext::new();++ let _ = ctx.compute_arc(&parent, &StatisticsArgs::new()).unwrap();+ drop(parent);+ drop(leaf);+ assert!(parent_weak.upgrade().is_some());+ assert!(leaf_weak.upgrade().is_some());++ ctx.reset_cache();+ assert!(parent_weak.upgrade().is_none());+ assert!(leaf_weak.upgrade().is_none());+ }++ #[test]+ fn owned_parent_and_leaf_are_released_when_context_drops() {+ let leaf = make_stats_leaf(10);+ let leaf_weak = Arc::downgrade(&leaf);+ let parent: Arc<dyn ExecutionPlan> =+ Arc::new(CoalescePartitionsExec::new(Arc::clone(&leaf)));+ let parent_weak = Arc::downgrade(&parent);++ {+ let ctx = StatisticsContext::new();+ let _ = ctx.compute_arc(&parent, &StatisticsArgs::new()).unwrap();+ drop(parent);+ drop(leaf);+ assert!(parent_weak.upgrade().is_some());+ assert!(leaf_weak.upgrade().is_some());+ }++ assert!(parent_weak.upgrade().is_none());+ assert!(leaf_weak.upgrade().is_none());+ }++ #[test]+ fn borrowed_parent_is_not_cached_but_retains_children() {+ let leaf = make_stats_leaf(10);+ let weak = Arc::downgrade(&leaf);+ let parent: Arc<dyn ExecutionPlan> =+ Arc::new(CoalescePartitionsExec::new(Arc::clone(&leaf)));+ let parent_key = cache_key(parent.as_ref(), None);+ let ctx = StatisticsContext::new();++ let _ = ctx+ .compute(parent.as_ref(), &StatisticsArgs::new())+ .unwrap();+ assert!(+ !ctx.cache.borrow().statistics.contains_key(&parent_key),+ "borrowed roots must not be memoized"+ );++ drop(parent);+ drop(leaf);+ assert!(weak.upgrade().is_some());++ ctx.reset_cache();+ assert!(weak.upgrade().is_none());+ }++ #[test]+ fn borrowed_compute_hits_root_cached_by_compute_arc() {+ let leaf = make_stats_leaf(10);+ let ctx = StatisticsContext::new();+ let args = StatisticsArgs::new();++ let owned = ctx.compute_arc(&leaf, &args).unwrap();+ let borrowed = ctx.compute(leaf.as_ref(), &args).unwrap();+ assert!(Arc::ptr_eq(&owned, &borrowed));+ }++ #[test]+ fn extension_cache_retains_plan_lifetime() {+ let leaf = make_stats_leaf(10);+ let weak = Arc::downgrade(&leaf);+ let ctx = ctx_with(Arc::new(TagLeafProvider { rows: 10, tag: 7 }));++ let _ = ctx+ .compute_extended_arc(&leaf, &StatisticsArgs::new())+ .unwrap();+ ctx.cache.borrow_mut().statistics.clear();+ drop(leaf);+ assert!(weak.upgrade().is_some());++ ctx.reset_cache();+ assert!(weak.upgrade().is_none());+ }+#[test]fn reset_cache_clears_entries() {let leaf = make_stats_leaf(10);let ctx = StatisticsContext::new();- let _ = ctx.compute(leaf.as_ref(), &StatisticsArgs::new()).unwrap();+ let _ = ctx.compute_arc(&leaf, &StatisticsArgs::new()).unwrap();assert!(!ctx.cache.borrow().statistics.is_empty());ctx.reset_cache();assert!(ctx.cache.borrow().statistics.is_empty());@@ -714,7 +928,9 @@ mod tests {// Fresh computation: returned even though no cached read was requested,// and still recorded for parents.- let (_, extensions) = ctx.compute_base(leaf.as_ref(), &args, false).unwrap();+ let (_, extensions) = ctx+ .compute_base(leaf.as_ref(), Some(&leaf), &args, false)+ .unwrap();assert_eq!(extensions.unwrap().get::<Tag>(), Some(&Tag(7)));assert!(ctx.cache@@ -724,9 +940,13 @@ mod tests {);// Cache hit: extensions are cloned out of the cache only on request.- let (_, extensions) = ctx.compute_base(leaf.as_ref(), &args, false).unwrap();+ let (_, extensions) = ctx+ .compute_base(leaf.as_ref(), Some(&leaf), &args, false)+ .unwrap();assert!(extensions.is_none());- let (_, extensions) = ctx.compute_base(leaf.as_ref(), &args, true).unwrap();+ let (_, extensions) = ctx+ .compute_base(leaf.as_ref(), Some(&leaf), &args, true)+ .unwrap();assert_eq!(extensions.unwrap().get::<Tag>(), Some(&Tag(7)));}