Date: Thu, 7 Sep 2023 20:16:21 -0400
From: Bruce Momjian <bruce@momjian.us>
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: Peter Eisentraut <peter.eisentraut@enterprisedb.com>,
	"Imseih (AWS), Sami" <simseih@amazon.com>,
	"pgsql-hackers@postgresql.org" <pgsql-hackers@postgresql.org>
Subject: Re: Correct the documentation for work_mem
Message-ID: <ZPpn1bDx8ZriAvQZ@momjian.us>
References: <66590882-F48C-4A25-83E3-73792CF8C51F@amazon.com>
 <d4052199-0f74-da33-9b5e-2250aea05edd@enterprisedb.com>
 <3363505.1682097301@sss.pgh.pa.us>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="KqmZzgI8Kh67ECZR"
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <3363505.1682097301@sss.pgh.pa.us>
Archived-At: <https://www.postgresql.org/message-id/ZPpn1bDx8ZriAvQZ%40momjian.us>
Precedence: bulk


--KqmZzgI8Kh67ECZR
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit

On Fri, Apr 21, 2023 at 01:15:01PM -0400, Tom Lane wrote:
> Peter Eisentraut <peter.eisentraut@enterprisedb.com> writes:
> > On 21.04.23 16:28, Imseih (AWS), Sami wrote:
> >> I suggest a small doc fix:
> >> “Note that for a complex query, several sort or hash operations might be 
> >> running simultaneously;”
> 
> > Here is a discussion of these terms: 
> > https://takuti.me/note/parallel-vs-concurrent/
> 
> > I think "concurrently" is the correct word here.
> 
> Probably, but it'd do little to remove the confusion Sami is on about,
> especially since the next sentence uses "concurrently" to describe the
> other case.  I think we need a more thorough rewording, perhaps like
> 
> -       Note that for a complex query, several sort or hash operations might be
> -       running in parallel; each operation will generally be allowed
> +       Note that a complex query may include several sort or hash
> +       operations; each such operation will generally be allowed
>         to use as much memory as this value specifies before it starts
>         to write data into temporary files.  Also, several running
>         sessions could be doing such operations concurrently.
> 
> I also find this wording a bit further down to be poor:
> 
>         Hash-based operations are generally more sensitive to memory
>         availability than equivalent sort-based operations.  The
>         memory available for hash tables is computed by multiplying
>         <varname>work_mem</varname> by
>         <varname>hash_mem_multiplier</varname>.  This makes it
> 
> I think "available" is not le mot juste, and it's also unclear from
> this whether we're speaking of the per-hash-table limit or some
> (nonexistent) overall limit.  How about
> 
> -       memory available for hash tables is computed by multiplying
> +       memory limit for a hash table is computed by multiplying

Adjusted patch attached.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Only you can decide what is important to you.

--KqmZzgI8Kh67ECZR
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="workmem.diff"

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 6bc1b215db..45d1bb4b7b 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1829,9 +1829,10 @@ include_dir 'conf.d'
         (such as a sort or hash table) before writing to temporary disk files.
         If this value is specified without units, it is taken as kilobytes.
         The default value is four megabytes (<literal>4MB</literal>).
-        Note that for a complex query, several sort or hash operations might be
-        running in parallel; each operation will generally be allowed
-        to use as much memory as this value specifies before it starts
+        Note that a complex query might perform several sort or hash
+        operations at the same time, with each operation generally being
+        allowed to use as much memory as this value specifies before
+        it starts
         to write data into temporary files.  Also, several running
         sessions could be doing such operations concurrently.
         Therefore, the total memory used could be many times the value
@@ -1845,7 +1846,7 @@ include_dir 'conf.d'
        <para>
         Hash-based operations are generally more sensitive to memory
         availability than equivalent sort-based operations.  The
-        memory available for hash tables is computed by multiplying
+        memory limit for a hash table is computed by multiplying
         <varname>work_mem</varname> by
         <varname>hash_mem_multiplier</varname>.  This makes it
         possible for hash-based operations to use an amount of memory

--KqmZzgI8Kh67ECZR--