Here's a first attempt at a new documentation chapter. This goes in
part "Server Programming", just after the SPI chapter.
I just noticed that worker_spi could use some more sample code, for
example auth_counter was getting its own LWLock and also its own shmem
area, which would be helpful to demonstrate I think.
--
Álvaro Herrera http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Training & Services
<!-- doc/src/sgml/bgworker.sgml -->
<chapter id="bgworker">
<title>Background Worker Processes</title>
<indexterm zone="bgworker">
<primary>Processes</primary>
<secondary>Additional</secondary>
</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 have a lifetime closely linked to the server's status.
These processes have the option to attach to <productname>PostgreSQL</>'s
shared memory area and connect to databases internally.
</para>
<warning>
<para>
There are considerable robustness and security risks in using background
worker processes, because them being written in the <literal>C</> language
gives them unrestricted access to data. Administrators wishing to enable
modules that include background worker process should exercise extreme
caution. Only carefully audited modules should be permitted to run
background worker processes.
</para>
</warning>
<para>
Only modules listed in <varname>shared_preload_libraries</> can run
background workers. A module wishing to register a background worker needs
to register it by calling
<function>RegisterBackgroundWorker(<type>BackgroundWorker
*worker</type>)</function>.
The structure <structname>BackgroundWorker</structname> is defined thus:
<programlisting>
typedef struct BackgroundWorker
{
char *bgw_name;
int bgw_flags;
BgWorkerStartTime bgw_start_time;
int bgw_restart_time; /* in seconds, or BGW_NEVER_RESTART */
bgworker_main_type bgw_main;
void *bgw_main_arg;
bgworker_sighdlr_type bgw_sighup;
bgworker_sighdlr_type bgw_sigterm;
} BackgroundWorker;
</programlisting>
</para>
<para>
<structfield>bgw_name</> is a string to be used in log messages, process
lists and similar contexts.
</para>
<para>
<structfield>bgw_flags</> is a bitwise-or'd bitmask indicating the
capabilities that the module would like to have. Possible values are
<literal>BGWORKER_SHMEM_ACCESS</literal> (requesting shared memory access)
and <literal>BGWORKER_BACKEND_DATABASE_CONNECTION</literal> (requesting the
ability to establish a database connection, through which it can later run
transactions and queries).
</para>
<para>
<structfield>bgw_start_time</structfield> is the server state during which
<command>postgres</> should start the process; it can be one of
<literal>BgWorkerStart_PostmasterStart</> (start as soon as
<command>postgres</> itself has finished its own initialization; processes
requesting this are not eligible for database connections),
<literal>BgWorkerStart_ConsistentState</> (start as soon as consistent state
has been reached in a HOT standby, allowing processes to connect to
databases and run read-only queries), and
<literal>BgWorkerStart_RecoveryFinished</> (start as soon as the system has
entered normal read-write state). Note the last two values are equivalent
in a server that's not a HOT standby.
</para>
<para>
<structfield>bgw_restart_time</structfield> is the interval, in seconds, that
<command>postgres</command> should wait before restarting the process,
in case it crashes. It can be any positive value, or
<literal>BGW_NEVER_RESTART</literal>, indicating not to restart the process in
case of a crash.
</para>
<para>
<structfield>bgw_main</structfield> is a pointer to the function to run once
the process is started. <structfield>bgw_main_arg</structfield> will be
passed to it as its only argument. Note that
<literal>MyBgworkerEntry</literal> is a pointer to a copy of the
<structname>BackgroundWorker</structname> structure passed
at registration time.
</para>
<para>
<structfield>bgw_sighup</structfield> and <structfield>bgw_sigterm</> are
pointers to functions that will be installed as signal handlers for the new
process.
</para>
<para>Once running, the process can connect to a database by calling
<function>BackgroundWorkerInitializeConnection(<parameter>char
*dbname</parameter>, <parameter>char *username</parameter>)</function>.
This allows the process to run transactions and queries using the
<literal>SPI</literal> interface. If <varname>dbname</> is NULL,
the session is not connected to any particular database, but shared catalogs
can be accessed. If <varname>username</> is NULL, the process will run as
the superuser created during <command>initdb</>.
</para>
<para>
Signals are initially blocked when control reaches the
<structfield>bgw_main</> function, and must be unblocked by it; this is to
allow the process to further customize its signal handlers, if necessary.
Signals can be unblocked in the new process by calling
<function>BackgroundWorkerUnblockSignals</> and blocked by calling
<function>BackgroundWorkerBlockSignals</>.
</para>
<para>
The <filename>worker_spi</> contrib module contains a working example,
which demonstrates some useful techniques.
</para>
</chapter>
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
