Re: doc: clarify wal_sender_shutdown_timeout behavior for small values

Hi

2026年7月17日(金) 14:37 Chao Li <li(dot)evan(dot)chao(at)gmail(dot)com>:
>
> Hi,
>
> While reading the doc for wal_sender_shutdown_timeout, I felt that it does not explicitly describe the behavior of a value of 0. According to the implementation, when wal_sender_shutdown_timeout is 0, the WAL sender terminates without waiting for the receiver to catch up by calling WalSndDoneImmediate(). When the value is very small, such as 1 millisecond, the timeout expires shortly afterward if the receiver has not already caught up, so from a user's perspective, the behavior may be very similar to that of 0.
>
> As I understand it, wal_sender_shutdown_timeout is intended to prevent shutdown from taking unexpectedly long. A value of 0 requests no waiting, while a value that is too small may provide insufficient time for the receiver to catch up. Such values should therefore be used with caution, especially for physical replication.
>
> The attached patch clarifies that the timeout is enabled for nonnegative values, documents the behavior of 0, and cautions users against setting a value too small for the receiver to catch up.

Rather than warn against "too small" values, which raises the question of how
you define "too small", I think it'd be better to note that you'd want a
value which is sufficiently high to ensure replication terminates properly under
normal circumstances (which will vary according to environment etc., so it will
be up to the user to work out what is best for them).

I took the liberty of revising your patch a bit (easier than trying to
describe suggested
changes in an email), which:

- moves the description of what a value of 0 does to the first
paragraph, which handles
what various values do
- revises the caution about small values to a note about selecting sufficiently
high values (per above)
- (nitpick) changed "nonnegative" to "non-negative", as that's the
majority variant in
the docs

> While touching this part of the doc, I also noticed that the preceding paragraph was missing one level of indentation and that there was no blank line between paragraphs. I was previously advised that paragraphs should be separated by a blank line, so the patch fixes these formatting issues as well.

+1, this matches the established formatting.

Regards

Ian Barwick