From: | Alvaro Herrera <alvherre(at)alvh(dot)no-ip(dot)org> |
---|---|
To: | Andres Freund <andres(at)anarazel(dot)de> |
Cc: | Bruce Momjian <bruce(at)momjian(dot)us>, pgsql-hackers(at)lists(dot)postgresql(dot)org |
Subject: | Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC |
Date: | 2023-11-14 16:49:59 |
Message-ID: | 202311141649.sjwd4c5kzzl6@alvherre.pgsql |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Thread: | |
Lists: | pgsql-committers pgsql-hackers |
Hola-hallo,
On 2023-Nov-13, Andres Freund wrote:
> On 2023-11-13 12:31:42 +0100, Alvaro Herrera wrote:
> > On 2023-Nov-09, Bruce Momjian wrote:
> >
> > > doc: fix wording describing the checkpoint_flush_after GUC
> >
> > Hmm. Is this new wording really more clear than the original wording?
> > I agree the original may not have been the most simple, but I don't
> > think it was wrong English.
>
> I think it was somewhat wrong (I probably wrote it) or at least awkwardly
> formulated. "force the OS that pages .. should be flushed" doesn't make a ton
> of sense.
Heh, you know what? I was mistaken. There was indeed a grammatical
error being fixed. The complaint [1] was that "you" was missing in the
sentence, and apparently that's correct [2].
[1] https://postgr.es/m/155208475619.1380.12815553062985622271@wrigleys.postgresql.org
[2] https://english.stackexchange.com/a/60285
So the core of the requested change was to turn "allows to force" into
"allows you to force". And this means that your new proposal:
> It probably should be something like:
> On Linux and POSIX platforms <xref linkend="guc-checkpoint-flush-after"/>
> allows to request that the OS flushes pages written by the checkpoint to disk
> after a configurable number of bytes. Otherwise, these [...]
would still fall afoul of the reported problem, because it still says
"allows to request", which is bad English.
> OTOH, the new formulation doesn't seem great either. The request(s) that we
> make to the OS are not guaranteed to be followed, so the "should be" was
> actually a correct part of the sentence.
Hmm, I hadn't noticed that nuance. Your text looks OK to me, except
that "... after a configurable number of bytes" reads odd after what's
already in the sentence. I would rewrite it in a different form, maybe
On Linux and POSIX platforms, checkpoint_flush_after specifies the
number of bytes written by a checkpoint after which the OS is requested
to flush pages to disk. Otherwise, these pages ...
Cheers
--
Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/
"Ninguna manada de bestias tiene una voz tan horrible como la humana" (Orual)
From | Date | Subject | |
---|---|---|---|
Next Message | Andres Freund | 2023-11-14 20:01:47 | Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC |
Previous Message | Robert Haas | 2023-11-14 16:06:15 | pgsql: Change how a base backup decides which files have checksums. |
From | Date | Subject | |
---|---|---|---|
Next Message | Nathan Bossart | 2023-11-14 17:01:15 | Re: retire MemoryContextResetAndDeleteChildren backwards compatibility macro |
Previous Message | Dagfinn Ilmari Mannsåker | 2023-11-14 16:36:44 | Re: retire MemoryContextResetAndDeleteChildren backwards compatibility macro |