Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <pgsql-hackers-owner+archive@lists.postgresql.org>)
	id 1ppuLm-0000NL-1N
	for pgsql-hackers@arkaria.postgresql.org; Fri, 21 Apr 2023 17:15:10 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.92)
	(envelope-from <pgsql-hackers-owner+archive@lists.postgresql.org>)
	id 1ppuLk-0006Qz-Sc
	for pgsql-hackers@arkaria.postgresql.org; Fri, 21 Apr 2023 17:15:08 +0000
Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29])
	by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1ppuLk-0006Qp-J4
	for pgsql-hackers@lists.postgresql.org; Fri, 21 Apr 2023 17:15:08 +0000
Received: from sss.pgh.pa.us ([66.207.139.130])
	by magus.postgresql.org with esmtps  (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.94.2)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1ppuLh-004HBY-SS
	for pgsql-hackers@postgresql.org; Fri, 21 Apr 2023 17:15:08 +0000
Received: from sss1.sss.pgh.pa.us (localhost [127.0.0.1])
	by sss.pgh.pa.us (8.15.2/8.15.2) with ESMTP id 33LHF10h3363506;
	Fri, 21 Apr 2023 13:15:01 -0400
From: Tom Lane <tgl@sss.pgh.pa.us>
To: Peter Eisentraut <peter.eisentraut@enterprisedb.com>
cc: "Imseih (AWS), Sami" <simseih@amazon.com>,
        "pgsql-hackers@postgresql.org" <pgsql-hackers@postgresql.org>
Subject: Re: Correct the documentation for work_mem
In-reply-to: <d4052199-0f74-da33-9b5e-2250aea05edd@enterprisedb.com>
References: <66590882-F48C-4A25-83E3-73792CF8C51F@amazon.com> <d4052199-0f74-da33-9b5e-2250aea05edd@enterprisedb.com>
Comments: In-reply-to Peter Eisentraut <peter.eisentraut@enterprisedb.com>
	message dated "Fri, 21 Apr 2023 18:59:57 +0200"
MIME-Version: 1.0
Content-Type: text/plain; charset="UTF-8"
Content-ID: <3363504.1682097301.1@sss.pgh.pa.us>
Content-Transfer-Encoding: quoted-printable
Date: Fri, 21 Apr 2023 13:15:01 -0400
Message-ID: <3363505.1682097301@sss.pgh.pa.us>
List-Id: <pgsql-hackers.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-hackers@lists.postgresql.org>
List-Owner: <mailto:pgsql-hackers-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-hackers>
Archived-At: <https://www.postgresql.org/message-id/3363505.1682097301%40sss.pgh.pa.us>
Precedence: bulk

Peter Eisentraut <peter.eisentraut@enterprisedb.com> writes:
> On 21.04.23 16:28, Imseih (AWS), Sami wrote:
>> I suggest a small doc fix:
>> =E2=80=9CNote that for a complex query, several sort or hash operations=
 might be =

>> running simultaneously;=E2=80=9D

> 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 mig=
ht 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

			regards, tom lane