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 -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
