Date: Mon, 11 Sep 2023 11:03:14 -0400
From: Bruce Momjian <bruce@momjian.us>
To: David Rowley <dgrowleyml@gmail.com>
Cc: "Imseih (AWS), Sami" <simseih@amazon.com>, Tom Lane <tgl@sss.pgh.pa.us>,
	Peter Eisentraut <peter.eisentraut@enterprisedb.com>,
	"pgsql-hackers@postgresql.org" <pgsql-hackers@postgresql.org>
Subject: Re: Correct the documentation for work_mem
Message-ID: <ZP8sMj4ZLj07AQe5@momjian.us>
References: <66590882-F48C-4A25-83E3-73792CF8C51F@amazon.com>
 <d4052199-0f74-da33-9b5e-2250aea05edd@enterprisedb.com>
 <3363505.1682097301@sss.pgh.pa.us>
 <ZPpn1bDx8ZriAvQZ@momjian.us>
 <CAApHDvrysy_z0ynH+TkK-YJ9fns0PN2y=RfB6oJaeS-7rhFgAQ@mail.gmail.com>
 <C0F1F23F-3F32-4B64-A31C-9FC92BE41A3F@amazon.com>
 <CAApHDvp2sAr9QLwucFLqz+uaO5iMxsy0uUEdoGTqw5r7iZ4Yzw@mail.gmail.com>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="6ydViZYVebu/Ug2p"
Content-Disposition: inline
In-Reply-To: <CAApHDvp2sAr9QLwucFLqz+uaO5iMxsy0uUEdoGTqw5r7iZ4Yzw@mail.gmail.com>
Archived-At: <https://www.postgresql.org/message-id/ZP8sMj4ZLj07AQe5%40momjian.us>
Precedence: bulk


--6ydViZYVebu/Ug2p
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

On Mon, Sep 11, 2023 at 10:02:55PM +1200, David Rowley wrote:
> On Sat, 9 Sept 2023 at 14:25, Imseih (AWS), Sami <simseih@amazon.com> wrote:
> >
> > > This looks mostly fine to me modulo "sort or hash". I do see many
> > > instances of "and/or" in the docs. Maybe that would work better.
> >
> > "sort or hash operations at the same time" is clear explanation IMO.
> 
> Just for anyone else following along that haven't seen the patch. The
> full text in question is:
> 
> +        Note that a complex query might perform several sort or hash
> +        operations at the same time, with each operation generally being
> 
> It's certainly not a show-stopper. I do believe the patch makes some
> improvements.  The reason I'd prefer to see either "and" or "and/or"
> in place of "or" is because the text is trying to imply that many of
> these operations can run at the same time. I'm struggling to
> understand why, given that there could be many sorts and many hashes
> going on at once that we'd claim it could only be one *or* the other.
> If we have 12 sorts and 4 hashes then that's not "several sort or hash
> operations", it's "several sort and hash operations".  Of course, it
> could just be sorts or just hashes, so "and/or" works fine for that.

Yes, I see your point and went with "and",   updated patch attached.

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

  Only you can decide what is important to you.

--6ydViZYVebu/Ug2p
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..8ed7ae57c2 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 and 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

--6ydViZYVebu/Ug2p--