executor: better comments (#48311)

pkg/executor/compiler.go

@@ -61,8 +61,11 @@ func (c *Compiler) Compile(ctx context.Context, stmtNode ast.StmtNode) (_ *ExecS
 
 	c.Ctx.GetSessionVars().StmtCtx.IsReadOnly = plannercore.IsReadOnly(stmtNode, c.Ctx.GetSessionVars())
 
+	// Do preprocess and validate.
 	ret := &plannercore.PreprocessorReturn{}
-	err = plannercore.Preprocess(ctx, c.Ctx,
+	err = plannercore.Preprocess(
+		ctx,
+		c.Ctx,
 		stmtNode,
 		plannercore.WithPreprocessorReturn(ret),
 		plannercore.InitTxnContextProvider,
@@ -85,18 +88,19 @@ func (c *Compiler) Compile(ctx context.Context, stmtNode ast.StmtNode) (_ *ExecS
 	stmtCtx := sessVars.StmtCtx
 	// handle the execute statement
 	var (
-		pointPlanShortPathOK bool
-		preparedObj          *plannercore.PlanCacheStmt
+		pointGetPlanShortPathOK bool
+		preparedObj             *plannercore.PlanCacheStmt
 	)
 
 	if execStmt, ok := stmtNode.(*ast.ExecuteStmt); ok {
 		if preparedObj, err = plannercore.GetPreparedStmt(execStmt, sessVars); err != nil {
 			return nil, err
 		}
-		if pointPlanShortPathOK, err = plannercore.IsPointPlanShortPathOK(c.Ctx, is, preparedObj); err != nil {
+		if pointGetPlanShortPathOK, err = plannercore.IsPointGetPlanShortPathOK(c.Ctx, is, preparedObj); err != nil {
 			return nil, err
 		}
 	}
+	// Build the final physical plan.
 	finalPlan, names, err := planner.Optimize(ctx, c.Ctx, stmtNode, is)
 	if err != nil {
 		return nil, err
@@ -127,7 +131,8 @@ func (c *Compiler) Compile(ctx context.Context, stmtNode ast.StmtNode) (_ *ExecS
 		OutputNames:   names,
 		Ti:            &TelemetryInfo{},
 	}
-	if pointPlanShortPathOK {
+	// Use cached plan if possible.
+	if pointGetPlanShortPathOK {
 		if ep, ok := stmt.Plan.(*plannercore.Execute); ok {
 			if pointPlan, ok := ep.Plan.(*plannercore.PointGetPlan); ok {
 				stmtCtx.SetPlan(stmt.Plan)
@@ -140,9 +145,12 @@ func (c *Compiler) Compile(ctx context.Context, stmtNode ast.StmtNode) (_ *ExecS
 			}
 		}
 	}
-	if err = sessiontxn.OptimizeWithPlanAndThenWarmUp(c.Ctx, stmt.Plan); err != nil {
+
+	// Perform optimization and initialization related to the transaction level.
+	if err = sessiontxn.AdviseOptimizeWithPlanAndThenWarmUp(c.Ctx, stmt.Plan); err != nil {
 		return nil, err
 	}
+
 	return stmt, nil
 }
 

pkg/planner/core/plan_cache.go

@@ -819,10 +819,10 @@ func GetBindSQL4PlanCache(sctx sessionctx.Context, stmt *PlanCacheStmt) (string,
 	return "", ignore
 }
 
-// IsPointPlanShortPathOK check if we can execute using plan cached in prepared structure
+// IsPointGetPlanShortPathOK check if we can execute using plan cached in prepared structure
 // Be careful with the short path, current precondition is ths cached plan satisfying
 // IsPointGetWithPKOrUniqueKeyByAutoCommit
-func IsPointPlanShortPathOK(sctx sessionctx.Context, is infoschema.InfoSchema, stmt *PlanCacheStmt) (bool, error) {
+func IsPointGetPlanShortPathOK(sctx sessionctx.Context, is infoschema.InfoSchema, stmt *PlanCacheStmt) (bool, error) {
 	stmtAst := stmt.PreparedAst
 	if stmtAst.CachedPlan == nil || staleread.IsStmtStaleness(sctx) {
 		return false, nil

pkg/planner/optimize.go

@@ -143,7 +143,6 @@ func getPlanFromNonPreparedPlanCache(ctx context.Context, sctx sessionctx.Contex
 }
 
 // Optimize does optimization and creates a Plan.
-// The node must be prepared first.
 func Optimize(ctx context.Context, sctx sessionctx.Context, node ast.Node, is infoschema.InfoSchema) (plan core.Plan, slice types.NameSlice, retErr error) {
 	sessVars := sctx.GetSessionVars()
 	if sessVars.StmtCtx.EnableOptimizerDebugTrace {
@@ -398,7 +397,6 @@ func Optimize(ctx context.Context, sctx sessionctx.Context, node ast.Node, is in
 }
 
 // OptimizeForForeignKeyCascade does optimization and creates a Plan for foreign key cascade.
-// The node must be prepared first.
 // Compare to Optimize, OptimizeForForeignKeyCascade only build plan by StmtNode,
 // doesn't consider plan cache and plan binding, also doesn't do privilege check.
 func OptimizeForForeignKeyCascade(ctx context.Context, sctx sessionctx.Context, node ast.StmtNode, is infoschema.InfoSchema) (core.Plan, error) {

pkg/sessiontxn/interface.go

@@ -102,9 +102,9 @@ type TxnAdvisable interface {
 	AdviseOptimizeWithPlan(plan interface{}) error
 }
 
-// OptimizeWithPlanAndThenWarmUp first do `AdviseOptimizeWithPlan` to optimize the txn with plan
+// AdviseOptimizeWithPlanAndThenWarmUp first do `AdviseOptimizeWithPlan` to optimize the txn with plan
 // and then do `AdviseWarmup` to do some tso fetch if necessary
-func OptimizeWithPlanAndThenWarmUp(sctx sessionctx.Context, plan interface{}) error {
+func AdviseOptimizeWithPlanAndThenWarmUp(sctx sessionctx.Context, plan interface{}) error {
 	txnManager := GetTxnManager(sctx)
 	if err := txnManager.AdviseOptimizeWithPlan(plan); err != nil {
 		return err