v3-0005-Document-find_em_expr_usable_for_sorting_rel-in-p.patch

From 714aacfea72dfa202457923befefa3a401309369 Mon Sep 17 00:00:00 2001
From: jcoleman <jtc331@gmail.com>
Date: Sun, 29 Nov 2020 09:13:02 -0500
Subject: [PATCH v3 5/5] Document find_em_expr_usable_for_sorting_rel in
 prepare_sort_from_pathkeys

---
 src/backend/optimizer/path/equivclass.c | 9 ++++++---
 src/backend/optimizer/plan/createplan.c | 3 +++
 2 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/src/backend/optimizer/path/equivclass.c b/src/backend/optimizer/path/equivclass.c
index e098b6066b..067c969100 100644
--- a/src/backend/optimizer/path/equivclass.c
+++ b/src/backend/optimizer/path/equivclass.c
@@ -798,9 +798,12 @@ find_em_expr_for_rel(EquivalenceClass *ec, RelOptInfo *rel)
 }
 
 /*
- * Find an equivalence class member expression that can be safely used by a
- * sort node on top of the provided relation. The rules here must match those
- * applied in prepare_sort_from_pathkeys.
+ * Find an equivalence class member expression that can be safely used to build
+ * a sort node using the provided relation. The applied rules parallel those
+ * applied in prepare_sort_from_pathkeys but are a subset of that function since
+ * here we are concerned with proactive sorts while prepare_sort_from_pathkeys
+ * must deal with sorts that must be delayed until the last stages of query
+ * execution.
  */
 Expr *
 find_em_expr_usable_for_sorting_rel(PlannerInfo *root, EquivalenceClass *ec, RelOptInfo *rel, bool require_parallel_safe)
diff --git a/src/backend/optimizer/plan/createplan.c b/src/backend/optimizer/plan/createplan.c
index 40abe6f9f6..db31ee6c0f 100644
--- a/src/backend/optimizer/plan/createplan.c
+++ b/src/backend/optimizer/plan/createplan.c
@@ -5848,6 +5848,9 @@ make_incrementalsort(Plan *lefttree, int numCols, int nPresortedCols,
  *
  * Returns the node which is to be the input to the Sort (either lefttree,
  * or a Result stacked atop lefttree).
+ *
+ * Note: Restrictions on what expressions are safely sortable may also need to
+ * be added to find_em_expr_usable_for_sorting_rel.
  */
 static Plan *
 prepare_sort_from_pathkeys(Plan *lefttree, List *pathkeys,
-- 
2.17.1