Skip to content

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.rs
index 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.rs
index 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 plan
diff --git a/datafusion/physical-plan/src/statistics.rs b/datafusion/physical-plan/src/statistics.rs
index 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)));
}