Thread: Improving the comments in pqsignal()

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.

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)

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.