Horton

Thread

Commits

  1. Improve comments about pqsignal().

  1. Improving the comments in pqsignal()

    Thomas Munro <thomas.munro@gmail.com> — 2023-11-23T22:33:29Z

    Hi,

While following along with Tristan and Heikki's thread about signals
in psql, it occurred to me that the documentation atop pqsignal() is
not very good:

 * we don't explain what problem it originally solved
 * we don't explain why it's still needed today
 * we don't explain what else it does for us today
 * we describe the backend implementation for Windows incorrectly (mea culpa)
 * we vaguely mention one issue with Windows frontend code, but I
think the point made is misleading, and we don't convey the scale of
the differences

Here is my attempt to improve it.

  2. Re: Improving the comments in pqsignal()

    Heikki Linnakangas <hlinnaka@iki.fi> — 2023-11-24T07:54:56Z

    On 24/11/2023 00:33, Thomas Munro wrote:
> Hi,
> 
> While following along with Tristan and Heikki's thread about signals
> in psql, it occurred to me that the documentation atop pqsignal() is
> not very good:
> 
>   * we don't explain what problem it originally solved
>   * we don't explain why it's still needed today
>   * we don't explain what else it does for us today
>   * we describe the backend implementation for Windows incorrectly (mea culpa)
>   * we vaguely mention one issue with Windows frontend code, but I
> think the point made is misleading, and we don't convey the scale of
> the differences
> 
> Here is my attempt to improve it.

Thanks!

> This is program 10.12 from Advanced Programming in the UNIX
> Environment, with minor changes.
In the copy I found online (3rd edition), it's "Figure 10.18", not 
"program 10.12".

Other than that, looks good.

-- 
Heikki Linnakangas
Neon (https://neon.tech)

  3. Re: Improving the comments in pqsignal()

    Thomas Munro <thomas.munro@gmail.com> — 2023-11-24T21:11:54Z

    On Fri, Nov 24, 2023 at 8:55 PM Heikki Linnakangas <hlinnaka@iki.fi> wrote:
> On 24/11/2023 00:33, Thomas Munro wrote:
> > This is program 10.12 from Advanced Programming in the UNIX
> > Environment, with minor changes.
> In the copy I found online (3rd edition), it's "Figure 10.18", not
> "program 10.12".
>
> Other than that, looks good.

Thanks.  I removed that number (it's easy enough to find), replaced
"underdocumented" with "unspecified" (a word from the later edition of
Stevens) and added a line break to break up that final paragraph, and
pushed.  Time to upgrade my treeware copy of that book...

One thing I worried about while writing that text: why is it OK that
win32_port.h redefines SIG_DFL etc, if they might be exposed to the
system signal()?  But it seems we picked the same numerical values.  A
little weird, but not going to break anything.