Apache DataFusion SQL Query Engine
docs: clarify ExecutionProps and TaskContext docs (#21872)
Andrew Lambbff0ffb682e7
diff --git a/datafusion/execution/src/task.rs b/datafusion/execution/src/task.rsindex 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 Iddiff --git a/datafusion/expr/src/execution_props.rs b/datafusion/expr/src/execution_props.rsindex 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`,