Thread: [patch] [doc] Clarify that signal functions have no feedback

On 2020-10-13 00:43, David G. Johnston wrote:
> Over in Bug# 16652 [1] Christoph failed to recognize the fact that 
> signal sending functions are inherently one-way just as signals are.  It 
> seems worth heading off this situation in the future by making it clear 
> how signals behave and, in the specific case of pg_reload_conf, that the 
> important feedback one would hope to get out of a success/failure 
> response from the function call must instead be found in other locations.

I agree that the documentation could be improved here.  But I don't see 
how the added advice actually helps in practice.  How can you detect 
reload errors by inspecting pg_settings etc.?

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

On 02/11/2020 18:02, David G. Johnston wrote:
> diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
> index bf6004f321..43bc2cf086 100644
> --- a/doc/src/sgml/func.sgml
> +++ b/doc/src/sgml/func.sgml
> @@ -23892,7 +23892,8 @@ SELECT collation for ('foo' COLLATE "de_DE");
>  
>     <para>
>      The functions shown in <xref
> -    linkend="functions-admin-signal-table"/> send control signals to
> +    linkend="functions-admin-signal-table"/> send uni-directional
> +    control signals to
>      other server processes.  Use of these functions is restricted to
>      superusers by default but access may be granted to others using
>      <command>GRANT</command>, with noted exceptions.

The "uni-directional" sounds a bit redundant, "send" implies that it's 
uni-directional I think.

> @@ -23900,7 +23901,8 @@ SELECT collation for ('foo' COLLATE "de_DE");
>  
>     <para>
>      Each of these functions returns <literal>true</literal> if
> -    successful and <literal>false</literal> otherwise.
> +    the signal was successfully sent and <literal>false</literal>
> +    if the sending of the signal failed.
>     </para>

This is a good clarification.

>     <table id="functions-admin-signal-table">
> @@ -23948,7 +23950,11 @@ SELECT collation for ('foo' COLLATE "de_DE");
>          server to reload their configuration files.  (This is initiated by
>          sending a <systemitem>SIGHUP</systemitem> signal to the postmaster
>          process, which in turn sends <systemitem>SIGHUP</systemitem> to each
> -        of its children.)
> +        of its children.)  Inspection of the relevant
> +        <link linkend="view-pg-file-settings">pg_file_settings</link>
> +        or
> +        <link linkend="view-pg-hba-file-rules">pg_hba_file_rules</link> views
> +        is recommended after making changes but before signaling the server.
>         </para></entry>
>        </row>

I don't understand this recommendation. What is the user supposed to 
look for in those views? And why before signaling the server?

[me reads what those views do]. Oh, I see, the idea is that you can use 
those views to check the configuration for errors, before applying the 
changes. How about this:

You can use the <link 
linkend="view-pg-file-settings">pg_file_settings</link> and <link 
linkend="view-pg-hba-file-rules">pg_hba_file_rules</link> views to check 
the configuration files for possible errors, before reloading.

- Heikki

On 17/11/2020 21:50, David G. Johnston wrote:
> On Tue, Nov 17, 2020 at 6:13 AM Heikki Linnakangas <hlinnaka@iki.fi 
> <mailto:hlinnaka@iki.fi>> wrote:
>     You can use the <link
>     linkend="view-pg-file-settings">pg_file_settings</link> and <link
>     linkend="view-pg-hba-file-rules">pg_hba_file_rules</link> views to
>     check
>     the configuration files for possible errors, before reloading.
> 
> 
> I agree with adding "why" you want to check those links, and added a bit 
> about why doing so before reloading works, but the phrasing using "You" 
> seems out-of-place in this region of the documentation.

There are plenty of "you"s in the docs. Matter of taste, for sure, but 
I'd prefer more active voice. Me being stubborn, I pushed this using my 
wording. :-)

Thanks!

- Heikki