From 523beaa11bdf6a9864e8978b467ed586b792c9ca Mon Sep 17 00:00:00 2001
From: Robert Haas <rhaas@postgresql.org>
Date: Fri, 18 Oct 2013 10:21:25 -0400
Subject: Provide a reliable mechanism for terminating a background worker.

Although previously-introduced APIs allow the process that registers a
background worker to obtain the worker's PID, there's no way to prevent
a worker that is not currently running from being restarted.  This
patch introduces a new API TerminateBackgroundWorker() that prevents
the background worker from being restarted, terminates it if it is
currently running, and causes it to be unregistered if or when it is
not running.

Patch by me.  Review by Michael Paquier and KaiGai Kohei.
---
 doc/src/sgml/bgworker.sgml | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/bgworker.sgml b/doc/src/sgml/bgworker.sgml
index 9e6dea98a24..6996d731868 100644
--- a/doc/src/sgml/bgworker.sgml
+++ b/doc/src/sgml/bgworker.sgml
@@ -184,13 +184,18 @@ typedef struct BackgroundWorker
    argument to <function>RegisterDynamicBackgroundWorker</function>.  If the
    worker is successfully registered, this pointer will be initialized with an
    opaque handle that can subsequently be passed to
-   <function>GetBackgroundWorkerPid(<parameter>BackgroundWorkerHandle *</parameter>, <parameter>pid_t *</parameter>)</function>.
-   This function can be used to poll the status of the worker: a return
-   value of <literal>BGWH_NOT_YET_STARTED</> indicates that the worker has not
-   yet been started by the postmaster; <literal>BGWH_STOPPED</literal>
-   indicates that it has been started but is no longer running; and
-   <literal>BGWH_STARTED</literal> indicates that it is currently running.
-   In this last case, the PID will also be returned via the second argument.
+   <function>GetBackgroundWorkerPid(<parameter>BackgroundWorkerHandle *</parameter>, <parameter>pid_t *</parameter>)</function> or
+   <function>TerminateBackgroundWorker(<parameter>BackgroundWorkerHandle *</parameter>)</function>.
+   <function>GetBackgroundWorker</> can be used to poll the status of the
+   worker: a return value of <literal>BGWH_NOT_YET_STARTED</> indicates that
+   the worker has not yet been started by the postmaster;
+   <literal>BGWH_STOPPED</literal> indicates that it has been started but is
+   no longer running; and <literal>BGWH_STARTED</literal> indicates that it is
+   currently running.  In this last case, the PID will also be returned via the
+   second argument.
+   <function>TerminateBackgroundWorker</> causes the postmaster to send
+   <literal>SIGTERM</> to the worker if it is running, and to unregister it
+   as soon as it is not.
   </para>
 
   <para>
-- 
cgit v1.2.3