Re: A couple of cosmetic changes around shared memory code

Robert Haas wrote:

> It might be better to document this in bgworker.sgml instead. That
> already documents some facts about exiting:
>
> <para>
> If <structfield>bgw_restart_time</structfield> for a background worker is
> configured as <literal>BGW_NEVER_RESTART</>, or if it exits with an exit
> code of 0 or is terminated by <function>TerminateBackgroundWorker</>,
> it will be automatically unregistered by the postmaster on exit.
> Otherwise, it will be restarted after the time period configured via
> <structfield>bgw_restart_time</>, or immediately if the postmaster
> reinitializes the cluster due to a backend failure. Backends which need
> to suspend execution only temporarily should use an interruptible sleep
> rather than exiting; this can be achieved by calling
> <function>WaitLatch()</function>. Make sure the
> <literal>WL_POSTMASTER_DEATH</> flag is set when calling that function, and
> verify the return code for a prompt exit in the emergency case that
> <command>postgres</> itself has terminated.
> </para>
>
> That paragraph leaves out a number of important details, like:
>
> 1. A background worker that exits with any exit code other than 0 or 1
> will cause a postmaster crash-and-restart cycle.
>
> 2. Therefore, an exit of code 1 should be used whenever the process
> wants to be restarted in accordance with bgw_restart_time, and is
> therefore in some sense the "normal" way for a background worker to
> exit.

Yeah, I think bgworker.sgml is the right place to document these
details.

> 3. The aforementioned details about how 9.3 behavior was different
> from current behavior.

Not really sure about this. I think patching the 9.3 docs to state the
details differently from the 9.4--master details would not be
sufficient, as people moving code would not read the 9.4 docs again to
ensure the semantics remain the same (and since 9.4 has been out for
awhile, patching the release notes wouldn't suffice either). Patching
the 9.3 docs to say "9.4 is different" would be odd, since 9.4 is "in
the future" for the POV of 9.3 docs.

I think the best option is to backpatch a doc change from 9.4 onwards
stating what is the new behavior, and add a note stating that 9.3 was
different.

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