Attempt to clarify comments related to force_parallel_mode.

Per discussion with Tom Lane.

Discussion: http://postgr.es/m/28589.1502902172@sss.pgh.pa.us

diff --git a/src/backend/optimizer/plan/planner.c b/src/backend/optimizer/plan/planner.c
index 407df9ae79db4fea76e8d035a3e5562e2f527efd..fdef00ab39c2ce505820f6881daad6bed62dd963 100644 (file)
--- a/src/backend/optimizer/plan/planner.c
+++ b/src/backend/optimizer/plan/planner.c
@@ -291,13 +291,21 @@ standard_planner(Query *parse, int cursorOptions, ParamListInfo boundParams)
    }
 
    /*
-    * glob->parallelModeNeeded should tell us whether it's necessary to
-    * impose the parallel mode restrictions, but we don't actually want to
-    * impose them unless we choose a parallel plan, so it is normally set
-    * only if a parallel plan is chosen (see create_gather_plan).  That way,
-    * people who mislabel their functions but don't use parallelism anyway
-    * aren't harmed.  But when force_parallel_mode is set, we enable the
-    * restrictions whenever possible for testing purposes.
+    * glob->parallelModeNeeded is normally set to false here and changed to
+    * true during plan creation if a Gather or Gather Merge plan is actually
+    * created (cf. create_gather_plan, create_gather_merge_plan).
+    *
+    * However, if force_parallel_mode = on or force_parallel_mode = regress,
+    * then we impose parallel mode whenever it's safe to do so, even if the
+    * final plan doesn't use parallelism.  It's not safe to do so if the
+    * query contains anything parallel-unsafe; parallelModeOK will be false
+    * in that case.  Note that parallelModeOK can't change after this point.
+    * Otherwise, everything in the query is either parallel-safe or
+    * parallel-restricted, and in either case it should be OK to impose
+    * parallel-mode restrictions.  If that ends up breaking something, then
+    * either some function the user included in the query is incorrectly
+    * labelled as parallel-safe or parallel-restricted when in reality it's
+    * parallel-unsafe, or else the query planner itself has a bug.
     */
    glob->parallelModeNeeded = glob->parallelModeOK &&
        (force_parallel_mode != FORCE_PARALLEL_OFF);