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.

2 files changed, 15 insertions, 6 deletions

diff --git a/src/include/postmaster/bgworker.h b/src/include/postmaster/bgworker.h
index 8bbbeb492c..c27b08bf1e 100644
--- a/src/include/postmaster/bgworker.h
+++ b/src/include/postmaster/bgworker.h
@@ -9,17 +9,22 @@
  * worker.	Workers can also be registered dynamically at runtime.  In either
  * case, the worker process is forked from the postmaster and runs the
  * user-supplied "main" function.  This code may connect to a database and
- * run transactions.  Once started, it stays active until shutdown or crash;
- * unless the restart interval is declared as BGW_NEVER_RESTART and the
- * process exits with a return code of 1; workers that do this are
- * automatically unregistered by the postmaster.
+ * run transactions.  Workers can remain active indefinitely, but will be
+ * terminated if a shutdown or crash occurs.
  *
  * If the fork() call fails in the postmaster, it will try again later.  Note
  * that the failure can only be transient (fork failure due to high load,
  * memory pressure, too many processes, etc); more permanent problems, like
  * failure to connect to a database, are detected later in the worker and dealt
- * with just by having the worker exit normally.  Postmaster will launch a new
- * worker again later.
+ * with just by having the worker exit normally.  A worker which exits with a
+ * return code of 0 will be immediately restarted by the postmaster.  A worker
+ * which exits with a return code of 1 will be restarted after the configured
+ * restart interval, or never if that interval is set to BGW_NEVER_RESTART.
+ * The TerminateBackgroundWorker() function can be used to terminate a
+ * dynamically registered background worker; the worker will be sent a SIGTERM
+ * and will not be restarted after it exits.  Whenever the postmaster knows
+ * that a worker will not be restarted, it unregisters the worker, freeing up
+ * that worker's slot for use by a new worker.
  *
  * Note that there might be more than one worker in a database concurrently,
  * and the same module may request more than one worker running the same (or
@@ -107,6 +112,9 @@ extern BgwHandleStatus GetBackgroundWorkerPid(BackgroundWorkerHandle *handle,
 extern BgwHandleStatus WaitForBackgroundWorkerStartup(BackgroundWorkerHandle *
 							   handle, pid_t *pid);
 
+/* Terminate a bgworker */
+extern void TerminateBackgroundWorker(BackgroundWorkerHandle *handle);
+
 /* This is valid in a running worker */
 extern BackgroundWorker *MyBgworkerEntry;
 
diff --git a/src/include/postmaster/bgworker_internals.h b/src/include/postmaster/bgworker_internals.h
index 6d5ee20dc3..e7e1ab94ad 100644
--- a/src/include/postmaster/bgworker_internals.h
+++ b/src/include/postmaster/bgworker_internals.h
@@ -31,6 +31,7 @@ typedef struct RegisteredBgWorker
 	int			rw_child_slot;
 	TimestampTz rw_crashed_at;	/* if not 0, time it last crashed */
 	int			rw_shmem_slot;
+	bool		rw_terminate;
 	slist_node	rw_lnode;		/* list link */
 } RegisteredBgWorker;