Clarify resource utilization of parallel query.

robertmhaas · robertmhaas · commit d1f822e58597 · 2016-07-07T11:35:08.000-04:00
temp_file_limit is a per-process limit, not a per-session limit across
all cooperating parallel processes; change wording accordingly, per a
suggestion from Tom Lane.

Also, document under max_parallel_workers_per_gather the fact that each
process involved in a parallel query may use as many resources as a
separate session.  Caveat emptor.

Per a complaint from Peter Geoghegan.
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
@@ -1603,7 +1603,7 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        Specifies the maximum amount of disk space that a session can use
+        Specifies the maximum amount of disk space that a process can use
         for temporary files, such as sort and hash temporary files, or the
         storage file for a held cursor.  A transaction attempting to exceed
         this limit will be canceled.
@@ -1613,7 +1613,7 @@ include_dir 'conf.d'
        </para>
        <para>
         This setting constrains the total space used at any instant by all
-        temporary files used by a given <productname>PostgreSQL</> session.
+        temporary files used by a given <productname>PostgreSQL</> process.
         It should be noted that disk space used for explicit temporary
         tables, as opposed to temporary files used behind-the-scenes in query
         execution, does <emphasis>not</emphasis> count against this limit.
@@ -2011,6 +2011,22 @@ include_dir 'conf.d'
          be inefficient.  The default value is 2.  Setting this value to 0
          disables parallel query execution.
         </para>
+
+        <para>
+         Note that parallel queries may consume very substantially more
+         resources than non-parallel queries, because each worker process is
+         a completely separate process which has roughly the same impact on the
+         system as an additional user session.  This should be taken into
+         account when choosing a value for this setting, as well as when
+         configuring other settings that control resource utilization, such
+         as <xref linkend="guc-work-mem">.  Resource limits such as
+         <varname>work_mem</> are applied individually to each worker,
+         which means the total utilization may be much higher across all
+         processes than it would normally be for any single process.
+         For example, a parallel query using 4 workers may use up to 5 times
+         as much CPU time, memory, I/O bandwidth, and so forth as a query which
+         uses no workers at all.
+        </para>
        </listitem>
       </varlistentry>
 
diff --git a/src/backend/utils/misc/guc.c b/src/backend/utils/misc/guc.c
@@ -1947,7 +1947,7 @@ static struct config_int ConfigureNamesInt[] =
 
 	{
 		{"temp_file_limit", PGC_SUSET, RESOURCES_DISK,
-			gettext_noop("Limits the total size of all temporary files used by each session."),
+			gettext_noop("Limits the total size of all temporary files used by each process."),
 			gettext_noop("-1 means no limit."),
 			GUC_UNIT_KB
 		},
diff --git a/src/backend/utils/misc/postgresql.conf.sample b/src/backend/utils/misc/postgresql.conf.sample
@@ -138,7 +138,7 @@
 
 # - Disk -
 
-#temp_file_limit = -1			# limits per-session temp file space
+#temp_file_limit = -1			# limits per-process temp file space
 					# in kB, or -1 for no limit
 
 # - Kernel Resource Usage -

Original file line number	Diff line number	Diff line change
`@@ -1947,7 +1947,7 @@ static struct config_int ConfigureNamesInt[] =`
`1947`	`1947`
`1948`	`1948`	`{`
`1949`	`1949`	`{"temp_file_limit", PGC_SUSET, RESOURCES_DISK,`
`1950`		`- gettext_noop("Limits the total size of all temporary files used by each session."),`
	`1950`	`+ gettext_noop("Limits the total size of all temporary files used by each process."),`
`1951`	`1951`	`gettext_noop("-1 means no limit."),`
`1952`	`1952`	`GUC_UNIT_KB`
`1953`	`1953`	`},`