Clarify resource utilization of parallel query.

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
index 061697b54cb1b996c3897478f5bb1cc2c8745875..4e8c982dd59f8df2cbbc25263914081eab61227a 100644 (file)
--- 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
index 60148b871b308d571fe727e018bf44fdd342a8f5..6ac5184b3743fe0aed88b1b3a6ee7a170f3a9f69 100644 (file)
--- 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
index a0abc2c2e0088635f9acd833e6c08cf81d6aae21..5faf22a37a5a67ddab2f92bf59b46ff01a64f876 100644 (file)
--- 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 -