Skip to content

Commit 5352ca2

Browse files
committed
Rename force_parallel_mode to debug_parallel_query
force_parallel_mode is meant to be used to allow us to exercise the parallel query infrastructure to ensure that it's working as we expect. It seems some users think this GUC is for forcing the query planner into picking a parallel plan regardless of the costs. A quick look at the documentation would have made them realize that they were wrong, but the GUC is likely too conveniently named which, evidently, seems to often result in users expecting that it forces the planner into usefully parallelizing queries. Here we rename the GUC to something which casual users are less likely to mistakenly think is what they need to make their query run more quickly. For now, the old name can still be used. We'll revisit if the old name mapping can be removed once the buildfarm configs are all updated. Reviewed-by: John Naylor Discussion: https://postgr.es/m/CAApHDvrsOi92_uA7PEaHZMH-S4Xv+MGhQWA+GrP8b1kjpS1HjQ@mail.gmail.com
1 parent 8e0e069 commit 5352ca2

File tree

23 files changed

+79
-76
lines changed

23 files changed

+79
-76
lines changed

doc/src/sgml/config.sgml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11091,17 +11091,17 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
1109111091
</listitem>
1109211092
</varlistentry>
1109311093

11094-
<varlistentry id="guc-force-parallel-mode" xreflabel="force_parallel_mode">
11095-
<term><varname>force_parallel_mode</varname> (<type>enum</type>)
11094+
<varlistentry id="guc-debug-parallel-query" xreflabel="debug_parallel_query">
11095+
<term><varname>debug_parallel_query</varname> (<type>enum</type>)
1109611096
<indexterm>
11097-
<primary><varname>force_parallel_mode</varname> configuration parameter</primary>
11097+
<primary><varname>debug_parallel_query</varname> configuration parameter</primary>
1109811098
</indexterm>
1109911099
</term>
1110011100
<listitem>
1110111101
<para>
1110211102
Allows the use of parallel queries for testing purposes even in cases
1110311103
where no performance benefit is expected.
11104-
The allowed values of <varname>force_parallel_mode</varname> are
11104+
The allowed values of <varname>debug_parallel_query</varname> are
1110511105
<literal>off</literal> (use parallel mode only when it is expected to improve
1110611106
performance), <literal>on</literal> (force parallel query for all queries
1110711107
for which it is thought to be safe), and <literal>regress</literal> (like

doc/src/sgml/regress.sgml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -370,7 +370,7 @@ make check LANG=C ENCODING=EUC_JP
370370
set in the <varname>PGOPTIONS</varname> environment variable (for settings
371371
that allow this):
372372
<screen>
373-
make check PGOPTIONS="-c force_parallel_mode=regress -c work_mem=50MB"
373+
make check PGOPTIONS="-c debug_parallel_query=regress -c work_mem=50MB"
374374
</screen>
375375
When running against a temporary installation, custom settings can also be
376376
set by supplying a pre-written <filename>postgresql.conf</filename>:

src/backend/access/transam/parallel.c

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1152,11 +1152,11 @@ HandleParallelMessage(ParallelContext *pcxt, int i, StringInfo msg)
11521152
* If desired, add a context line to show that this is a
11531153
* message propagated from a parallel worker. Otherwise, it
11541154
* can sometimes be confusing to understand what actually
1155-
* happened. (We don't do this in FORCE_PARALLEL_REGRESS mode
1155+
* happened. (We don't do this in DEBUG_PARALLEL_REGRESS mode
11561156
* because it causes test-result instability depending on
11571157
* whether a parallel worker is actually used or not.)
11581158
*/
1159-
if (force_parallel_mode != FORCE_PARALLEL_REGRESS)
1159+
if (debug_parallel_query != DEBUG_PARALLEL_REGRESS)
11601160
{
11611161
if (edata.context)
11621162
edata.context = psprintf("%s\n%s", edata.context,

src/backend/commands/explain.c

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -756,8 +756,8 @@ ExplainPrintPlan(ExplainState *es, QueryDesc *queryDesc)
756756
/*
757757
* Sometimes we mark a Gather node as "invisible", which means that it's
758758
* not to be displayed in EXPLAIN output. The purpose of this is to allow
759-
* running regression tests with force_parallel_mode=regress to get the
760-
* same results as running the same tests with force_parallel_mode=off.
759+
* running regression tests with debug_parallel_query=regress to get the
760+
* same results as running the same tests with debug_parallel_query=off.
761761
* Such marking is currently only supported on a Gather at the top of the
762762
* plan. We skip that node, and we must also hide per-worker detail data
763763
* further down in the plan tree.

src/backend/optimizer/plan/planmain.c

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -114,12 +114,12 @@ query_planner(PlannerInfo *root,
114114
* Anything parallel-restricted in the query tlist will be
115115
* dealt with later.) This is normally pretty silly, because
116116
* a Result-only plan would never be interesting to
117-
* parallelize. However, if force_parallel_mode is on, then
117+
* parallelize. However, if debug_parallel_query is on, then
118118
* we want to execute the Result in a parallel worker if
119119
* possible, so we must do this.
120120
*/
121121
if (root->glob->parallelModeOK &&
122-
force_parallel_mode != FORCE_PARALLEL_OFF)
122+
debug_parallel_query != DEBUG_PARALLEL_OFF)
123123
final_rel->consider_parallel =
124124
is_parallel_safe(root, parse->jointree->quals);
125125

src/backend/optimizer/plan/planner.c

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@
7070

7171
/* GUC parameters */
7272
double cursor_tuple_fraction = DEFAULT_CURSOR_TUPLE_FRACTION;
73-
int force_parallel_mode = FORCE_PARALLEL_OFF;
73+
int debug_parallel_query = DEBUG_PARALLEL_OFF;
7474
bool parallel_leader_participation = true;
7575

7676
/* Hook for plugins to get control in planner() */
@@ -364,20 +364,20 @@ standard_planner(Query *parse, const char *query_string, int cursorOptions,
364364
* true during plan creation if a Gather or Gather Merge plan is actually
365365
* created (cf. create_gather_plan, create_gather_merge_plan).
366366
*
367-
* However, if force_parallel_mode = on or force_parallel_mode = regress,
368-
* then we impose parallel mode whenever it's safe to do so, even if the
369-
* final plan doesn't use parallelism. It's not safe to do so if the
370-
* query contains anything parallel-unsafe; parallelModeOK will be false
371-
* in that case. Note that parallelModeOK can't change after this point.
372-
* Otherwise, everything in the query is either parallel-safe or
367+
* However, if debug_parallel_query = on or debug_parallel_query =
368+
* regress, then we impose parallel mode whenever it's safe to do so, even
369+
* if the final plan doesn't use parallelism. It's not safe to do so if
370+
* the query contains anything parallel-unsafe; parallelModeOK will be
371+
* false in that case. Note that parallelModeOK can't change after this
372+
* point. Otherwise, everything in the query is either parallel-safe or
373373
* parallel-restricted, and in either case it should be OK to impose
374374
* parallel-mode restrictions. If that ends up breaking something, then
375375
* either some function the user included in the query is incorrectly
376376
* labeled as parallel-safe or parallel-restricted when in reality it's
377377
* parallel-unsafe, or else the query planner itself has a bug.
378378
*/
379379
glob->parallelModeNeeded = glob->parallelModeOK &&
380-
(force_parallel_mode != FORCE_PARALLEL_OFF);
380+
(debug_parallel_query != DEBUG_PARALLEL_OFF);
381381

382382
/* Determine what fraction of the plan is likely to be scanned */
383383
if (cursorOptions & CURSOR_OPT_FAST_PLAN)
@@ -431,7 +431,7 @@ standard_planner(Query *parse, const char *query_string, int cursorOptions,
431431
* Optionally add a Gather node for testing purposes, provided this is
432432
* actually a safe thing to do.
433433
*/
434-
if (force_parallel_mode != FORCE_PARALLEL_OFF && top_plan->parallel_safe)
434+
if (debug_parallel_query != DEBUG_PARALLEL_OFF && top_plan->parallel_safe)
435435
{
436436
Gather *gather = makeNode(Gather);
437437

@@ -449,7 +449,7 @@ standard_planner(Query *parse, const char *query_string, int cursorOptions,
449449
gather->plan.righttree = NULL;
450450
gather->num_workers = 1;
451451
gather->single_copy = true;
452-
gather->invisible = (force_parallel_mode == FORCE_PARALLEL_REGRESS);
452+
gather->invisible = (debug_parallel_query == DEBUG_PARALLEL_REGRESS);
453453

454454
/*
455455
* Since this Gather has no parallel-aware descendants to signal to,

src/backend/utils/misc/guc.c

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -186,6 +186,7 @@ static const unit_conversion time_unit_conversion_table[] =
186186
static const char *const map_old_guc_names[] = {
187187
"sort_mem", "work_mem",
188188
"vacuum_mem", "maintenance_work_mem",
189+
"force_parallel_mode", "debug_parallel_query",
189190
NULL
190191
};
191192

src/backend/utils/misc/guc_tables.c

Lines changed: 17 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -360,16 +360,16 @@ static const struct config_enum_entry recovery_prefetch_options[] = {
360360
{NULL, 0, false}
361361
};
362362

363-
static const struct config_enum_entry force_parallel_mode_options[] = {
364-
{"off", FORCE_PARALLEL_OFF, false},
365-
{"on", FORCE_PARALLEL_ON, false},
366-
{"regress", FORCE_PARALLEL_REGRESS, false},
367-
{"true", FORCE_PARALLEL_ON, true},
368-
{"false", FORCE_PARALLEL_OFF, true},
369-
{"yes", FORCE_PARALLEL_ON, true},
370-
{"no", FORCE_PARALLEL_OFF, true},
371-
{"1", FORCE_PARALLEL_ON, true},
372-
{"0", FORCE_PARALLEL_OFF, true},
363+
static const struct config_enum_entry debug_parallel_query_options[] = {
364+
{"off", DEBUG_PARALLEL_OFF, false},
365+
{"on", DEBUG_PARALLEL_ON, false},
366+
{"regress", DEBUG_PARALLEL_REGRESS, false},
367+
{"true", DEBUG_PARALLEL_ON, true},
368+
{"false", DEBUG_PARALLEL_OFF, true},
369+
{"yes", DEBUG_PARALLEL_ON, true},
370+
{"no", DEBUG_PARALLEL_OFF, true},
371+
{"1", DEBUG_PARALLEL_ON, true},
372+
{"0", DEBUG_PARALLEL_OFF, true},
373373
{NULL, 0, false}
374374
};
375375

@@ -4852,13 +4852,15 @@ struct config_enum ConfigureNamesEnum[] =
48524852
},
48534853

48544854
{
4855-
{"force_parallel_mode", PGC_USERSET, DEVELOPER_OPTIONS,
4856-
gettext_noop("Forces use of parallel query facilities."),
4857-
gettext_noop("If possible, run query using a parallel worker and with parallel restrictions."),
4855+
{"debug_parallel_query", PGC_USERSET, DEVELOPER_OPTIONS,
4856+
gettext_noop("Forces the planner's use parallel query nodes."),
4857+
gettext_noop("This can be useful for testing the parallel query infrastructure "
4858+
"by forcing the planner to generate plans which contains nodes "
4859+
"which perform tuple communication between workers and the main process."),
48584860
GUC_NOT_IN_SAMPLE | GUC_EXPLAIN
48594861
},
4860-
&force_parallel_mode,
4861-
FORCE_PARALLEL_OFF, force_parallel_mode_options,
4862+
&debug_parallel_query,
4863+
DEBUG_PARALLEL_OFF, debug_parallel_query_options,
48624864
NULL, NULL, NULL
48634865
},
48644866

src/include/optimizer/optimizer.h

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -99,16 +99,16 @@ extern bool is_pseudo_constant_for_index(PlannerInfo *root, Node *expr,
9999

100100
/* in plan/planner.c: */
101101

102-
/* possible values for force_parallel_mode */
102+
/* possible values for debug_parallel_query */
103103
typedef enum
104104
{
105-
FORCE_PARALLEL_OFF,
106-
FORCE_PARALLEL_ON,
107-
FORCE_PARALLEL_REGRESS
108-
} ForceParallelMode;
105+
DEBUG_PARALLEL_OFF,
106+
DEBUG_PARALLEL_ON,
107+
DEBUG_PARALLEL_REGRESS
108+
} DebugParallelMode;
109109

110110
/* GUC parameters */
111-
extern PGDLLIMPORT int force_parallel_mode;
111+
extern PGDLLIMPORT int debug_parallel_query;
112112
extern PGDLLIMPORT bool parallel_leader_participation;
113113

114114
extern struct PlannedStmt *planner(Query *parse, const char *query_string,

src/pl/plpgsql/src/pl_exec.c

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8066,7 +8066,7 @@ exec_save_simple_expr(PLpgSQL_expr *expr, CachedPlan *cplan)
80668066

80678067
/*
80688068
* Ordinarily, the plan node should be a simple Result. However, if
8069-
* force_parallel_mode is on, the planner might've stuck a Gather node
8069+
* debug_parallel_query is on, the planner might've stuck a Gather node
80708070
* atop that. The simplest way to deal with this is to look through the
80718071
* Gather node. The Gather node's tlist would normally contain a Var
80728072
* referencing the child node's output, but it could also be a Param, or

0 commit comments

Comments
 (0)