Home • Explore • Blog • CI
☰



postgresql
5th chunk of `doc/src/sgml/bgworker.sgml`
5dd45d7c9e309894b8f92755142fefd0906cd8b1505ca01300000001000007ed
 this can be achieved by calling
   <function>WaitLatch()</function>. Make sure the
   <literal>WL_POSTMASTER_DEATH</literal> flag is set when calling that function, and
   verify the return code for a prompt exit in the emergency case that
   <command>postgres</command> itself has terminated.
  </para>

  <para>
   When a background worker is registered using the
   <function>RegisterDynamicBackgroundWorker</function> function, it is
   possible for the backend performing the registration to obtain information
   regarding the status of the worker.  Backends wishing to do this should
   pass the address of a <type>BackgroundWorkerHandle *</type> as the second
   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> or
   <function>TerminateBackgroundWorker(<parameter>BackgroundWorkerHandle *</parameter>)</function>.
   <function>GetBackgroundWorkerPid</function> can be used to poll the status of the
   worker: a return value of <literal>BGWH_NOT_YET_STARTED</literal> 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</function> causes the postmaster to send
   <literal>SIGTERM</literal> to the worker if it is running, and to unregister it
   as soon as it is not.
  </para>

  <para>
   In some cases, a process which registers a background worker may wish to
   wait for the worker to start up.  This can be accomplished by initializing
   <structfield>bgw_notify_pid</structfield> to <literal>MyProcPid</literal>
Title: Background Worker Registration, Status Monitoring, and Termination
Summary
Background workers that need to temporarily suspend execution should use WaitLatch() with WL_POSTMASTER_DEATH and check the return code. RegisterDynamicBackgroundWorker allows the registering backend to get worker status via a BackgroundWorkerHandle. GetBackgroundWorkerPid retrieves the PID and status (BGWH_NOT_YET_STARTED, BGWH_STOPPED, BGWH_STARTED). TerminateBackgroundWorker sends SIGTERM to the worker and unregisters it.