You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@datafusion.apache.org by gi...@apache.org on 2026/04/27 14:46:48 UTC
(datafusion) 01/01: docs: clarify ExecutionProps and TaskContext docs (#21872)
This is an automated email from the ASF dual-hosted git repository.
github-merge-queue[bot] pushed a commit to branch gh-readonly-queue/main/pr-21872-68061a584ffb90a045c6a2f3a3f3720d40fbbc08
in repository https://gitbox.apache.org/repos/asf/datafusion.git
commit bff0ffb682e723669a65584e6757d81264ce00db
Author: Andrew Lamb <an...@nerdnetworks.org>
AuthorDate: Mon Apr 27 10:46:25 2026 -0400
docs: clarify ExecutionProps and TaskContext docs (#21872)
## Which issue does this PR close?
- Follow on to https://github.com/apache/datafusion/pull/21240
## Rationale for this change
While reviewing https://github.com/apache/datafusion/pull/21240 I found
that the existing doc comments describing the relationship between
ExecutionProps and TaskContext were vague
## What changes are included in this PR?
- Update the doc comments on ExecutionProps and TaskContext
- Clarify why the two structures remain separate
## Are these changes tested?
Not with automated tests. This is a comment-only change.
## Are there any user-facing changes?
Docs only
---
datafusion/execution/src/task.rs | 16 ++++++++++++++++
datafusion/expr/src/execution_props.rs | 21 +++++++++++++++++++--
2 files changed, 35 insertions(+), 2 deletions(-)
diff --git a/datafusion/execution/src/task.rs b/datafusion/execution/src/task.rs
index 38f31cf462..eadf3ea8ac 100644
--- a/datafusion/execution/src/task.rs
+++ b/datafusion/execution/src/task.rs
@@ -31,7 +31,23 @@ use std::{collections::HashMap, sync::Arc};
/// execution. Please see the documentation on [`SessionContext`] for more
/// information.
///
+/// # Relationship with [`ExecutionProps`]
+///
+/// [`TaskContext`] is intentionally distinct from [`ExecutionProps`].
+/// [`ExecutionProps`] is state used while optimizing a logical
+/// plan and constructing a physical plan.
+///
+/// [`TaskContext`] is the runtime context passed to physical operators when
+/// executing a physical plan. It carries runtime services and session state
+/// needed at that stage, such as [`RuntimeEnv`], memory-pool access, session
+/// configuration, and function lookup.
+///
+/// Keeping these structures separate avoids threading execution/runtime state
+/// through planning APIs, and avoids making execution depend on planner-only
+/// scratch state.
+///
/// [`SessionContext`]: https://docs.rs/datafusion/latest/datafusion/execution/context/struct.SessionContext.html
+/// [`ExecutionProps`]: datafusion_expr::execution_props::ExecutionProps
#[derive(Debug)]
pub struct TaskContext {
/// Session Id
diff --git a/datafusion/expr/src/execution_props.rs b/datafusion/expr/src/execution_props.rs
index 3bf6978eb6..ff53dc495f 100644
--- a/datafusion/expr/src/execution_props.rs
+++ b/datafusion/expr/src/execution_props.rs
@@ -22,8 +22,9 @@ use datafusion_common::alias::AliasGenerator;
use datafusion_common::config::ConfigOptions;
use std::sync::Arc;
-/// Holds per-query execution properties and data (such as statement
-/// starting timestamps).
+/// Holds properties and scratch state used while optimizing a [`LogicalPlan`]
+/// and translating it into an executable physical plan, such as the statement
+/// start time used during simplification.
///
/// An [`ExecutionProps`] is created each time a `LogicalPlan` is
/// prepared for execution (optimized). If the same plan is optimized
@@ -31,6 +32,22 @@ use std::sync::Arc;
///
/// It is important that this structure be cheap to create as it is
/// done so during predicate pruning and expression simplification
+///
+/// # Relationship with [`TaskContext`]
+///
+/// [`ExecutionProps`] is intentionally distinct from [`TaskContext`].
+/// It is used while optimizing a logical plan and constructing physical
+/// expressions and physical plans, before physical operators are run.
+///
+/// [`TaskContext`] is the runtime context passed to physical operators during
+/// physical-plan execution.
+///
+/// Keeping these structures separate avoids threading execution/runtime state
+/// through planning APIs, and avoids making execution depend on planner-only
+/// scratch state.
+///
+/// [`TaskContext`]: https://docs.rs/datafusion/latest/datafusion/execution/struct.TaskContext.html
+/// [`LogicalPlan`]: crate::LogicalPlan
#[derive(Clone, Debug)]
pub struct ExecutionProps {
/// The time at which the query execution started. If `None`,
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datafusion.apache.org
For additional commands, e-mail: commits-help@datafusion.apache.org