On 2012-12-05 12:09:58 -0300, Alvaro Herrera wrote:
> 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.
I am not exactly renowned for my english skills, but I have made a pass
over the file made some slight changes and extended it in two places.
I've also added a comment with a question that came to my mind when
reading the docs...
Greetings,
Andres Freund
--
Andres Freund http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Training & Services
--- /tmp/bgworker.old.sgml 2012-12-05 22:12:00.220609454 +0100
+++ /tmp/bgworker.sgml 2012-12-05 22:26:11.604712943 +0100
@@ -11,16 +11,16 @@
<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.
+ which permits them to 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.
+ shared memory area and to 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
+ worker processes because, being written in the <literal>C</> language,
+ they have 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.
@@ -31,7 +31,8 @@
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>.
+ <function>RegisterBackgroundWorker(<type>BackgroundWorker *worker</type>)</function>
+ from it's <function>_PG_Init()</>.
The structure <structname>BackgroundWorker</structname> is defined thus:
<programlisting>
typedef struct BackgroundWorker
@@ -50,12 +51,12 @@
<para>
<structfield>bgw_name</> is a string to be used in log messages, process
- lists and similar contexts.
+ listings 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
+ capabilities that the module wants. 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
@@ -68,33 +69,35 @@
<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
+ <literal>BgWorkerStart_ConsistentState</> (start as soon as a 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.
+ <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.
+ passed to it as its only argument. Note that the global variable
+ <literal>MyBgworkerEntry</literal> points 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.
+ process. XXX: Can they be NULL?
</para>
<para>Once running, the process can connect to a database by calling
@@ -104,6 +107,8 @@
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</>.
+ BackgroundWorkerInitializeConnection can only be called once per background
+ process, it is not possible to switch databases.
</para>
<para>
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
