<!-- doc/src/sgml/bgworker.sgml -->

<chapter id="bgworker">
 <title>Background Worker Processes</title>

 <indexterm zone="bgworker">
  <primary>Background workers</primary>
 </indexterm>

 <para>
  PostgreSQL can be extended to run user-supplied code in separate processes.
  Such processes are started, stopped and monitored by <command>postgres</command>,
  which permits them to have a lifetime closely linked to the server's status.
  These processes are attached to <productname>PostgreSQL</productname>'s
  shared memory area and have the option to connect to databases internally; they can also run
  multiple transactions serially, just like a regular client-connected server
  process.  Also, by linking to <application>libpq</application> they can connect to the
  server and behave like a regular client application.
 </para>

 <warning>
  <para>
   There are considerable robustness and security risks in using background
   worker processes because, being written in the <literal>C</literal> language,
   they have unrestricted access to data.  Administrators wishing to enable
   modules that include background worker processes should exercise extreme
   caution.  Only carefully audited modules should be permitted to run
   background worker processes.
  </para>
 </warning>

 <para>
  Background workers can be initialized at the time that
  <productname>PostgreSQL</productname> is started by including the module name in
  <varname>shared_preload_libraries</varname>.  A module wishing to run a background
  worker can register it by calling
  <function>RegisterBackgroundWorker(<type>BackgroundWorker</type>
  *<parameter>worker</parameter>)</function>
  from its <function>_PG_init()</function> function.
  Background workers can also be started
  after the system is up and running by calling
  <function>RegisterDynamicBackgroundWorker(<type>BackgroundWorker</type>
  *<parameter>worker</parameter>, <type>BackgroundWorkerHandle</type>
  **<parameter>handle</parameter>)</function>.  Unlike
  <function>RegisterBackgroundWorker</function>, which can only be called from
  within the postmaster process,
  <function>RegisterDynamicBackgroundWorker</function> must be called
  from a regular backend or another background worker.
 </para>

 <para>
  The structure <structname>BackgroundWorker</structname> is defined thus:
<programlisting>
typedef void (*bgworker_main_type)(Datum main_arg);
typedef struct BackgroundWorker
{
    char        bgw_name[BGW_MAXLEN];
    char        bgw_type[BGW_MAXLEN];
    int         bgw_flags;
    BgWorkerStartTime bgw_start_time;
    int         bgw_restart_time;       /* in seconds, or BGW_NEVER_RESTART */
    char        bgw_library_name[MAXPGPATH];
    char        bgw_function_name[BGW_MAXLEN];
    Datum       bgw_main_arg;
    char        bgw_extra[BGW_EXTRALEN];
    pid_t       bgw_notify_pid;
} BackgroundWorker;
</programlisting>
  </para>

  <para>
   <structfield>bgw_name</structfield> and <structfield>bgw_type</structfield> are
   strings to be used in log messages, process listings and similar contexts.
   <structfield>bgw_type</structfield> should be the same for all background
   workers of the same type, so that it is possible to group such workers in a
   process listing, for example.  <structfield>bgw_name</structfield> on the
   other hand can contain additional information about the specific process.
   (Typically, the string for <structfield>bgw_name</structfield> will contain
   the type somehow, but that is not strictly required.)
  </para>

  <para>
   <structfield>bgw_flags</structfield> is a bitwise-or'd bit mask indicating the
   capabilities that the module wants.  Possible values are:
   <variablelist>

    <varlistentry>
     <term><literal>BGWORKER_SHMEM_ACCESS</literal></term>
     <listitem>
      <para>
       <indexterm><primary>BGWORKER_SHMEM_ACCESS</primary></indexterm>
       Requests shared memory access.  This flag is required.
      </para>
     </listitem>
    </varlistentry>