Skip to content

Commit

Permalink
Merge branch 'pr/9'
Browse files Browse the repository at this point in the history
  • Loading branch information
@gleu
gleu committed May 30, 2013
2 parents 3b74b6a + c42654c commit 5a3dc58
Show file tree
Hide file tree
Showing 2 changed files with 155 additions and 141 deletions.
166 changes: 86 additions & 80 deletions postgresql/bgworker.xml
View file
Original file line number Diff line number Diff line change
@@ -1,41 +1,43 @@
<!-- doc/src/sgml/bgworker.sgml -->

<chapter id="bgworker">
<title>Background Worker Processes</title>
<title>Processus en tâche de fond (background worker)</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 have the option to attach to <productname>PostgreSQL</productname>'s
shared memory area and 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.
PostgreSQL peut être étendu pour lancer du code utilisateur dans des processus
séparés. Ces processus sont démarrés, arrêtés et supervisés par
<command>postgres</command>, ce qui leur permet d'avoir un cycle de vie étroitement
lié au statut du serveur. Ces processus ont des options pour s'attacher à la
zone de mémoire partagée de <productname>PostgreSQL</productname> et pour se
connecter aux bases de manière interne&nbsp;; ils peuvent également exécuter de
multiples transactions séquentiellement, comme n'importe quel processus client
standard connecté au serveur. De plus, en se liant avec la bibliothèque
<application>libpq</application>, ils peuvent se connecter au serveur et se comporter
comme une application cliente standard.
</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 process should exercise extreme
caution. Only carefully audited modules should be permitted to run
background worker processes.
Il y a de considérables risques de robustesse et sécurité lorsque l'on utilise
des processus background worker. En effet, ceux-ci étant écrit en langage
<literal>C</literal>, ils ont un accès total aux données. Les administrateurs
désirant activer des modules incluant des processus background worker devraient
prendre énormément de précautions. Seuls les modules soigneusement testés
devraient être autorisés à lancer des processus background worker.
</para>
</warning>

<para>
Only modules listed in <varname>shared_preload_libraries</varname> can run
background workers. A module wishing to run a background worker needs
to register it by calling
Seuls les modules listés dans <varname>shared_preload_library</varname> peuvent
démarrer des background workers. Un module désirant démarrer un background
worker doit l'enregistrer en appelant
<function>RegisterBackgroundWorker(<type>BackgroundWorker *worker</type>)</function>
from its <function>_PG_init()</function>.
The structure <structname>BackgroundWorker</structname> is defined thus:
dans son <function>_PG_init()</function>.
La structure <structname>BackgroundWorker</structname> est définie ainsi&nbsp;:
<programlisting>
typedef void (*bgworker_main_type)(void *main_arg);
typedef void (*bgworker_sighdlr_type)(SIGNAL_ARGS);
Expand All @@ -54,93 +56,97 @@ typedef struct BackgroundWorker
</para>

<para>
<structfield>bgw_name</structfield> is a string to be used in log messages, process
listings and similar contexts.
<structfield>bgw_name</structfield> est une chaîne de caractères à utiliser
dans les messages de trace, liste de processus et autres listes similaires.
</para>

<para>
<structfield>bgw_flags</structfield> is a bitwise-or'd bitmask indicating the
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
transactions and queries).
<structfield>bgw_flags</structfield> est un masque de bit OR indiquant les
capacités que veut le module. Les valeurs possibles sont
<literal>BGWORKER_SHMEM_ACCESS</literal> (demandant un accès à la mémoire partagée)
et <literal>BGWORKER_BACKEND_DATABASE_CONNECTION</literal> (demandant la capacité
d'établir une connexion à la base, grâce à laquelle il pourra exécuter des
transactions et requêtes ultérieurement).
</para>

<para>
<structfield>bgw_start_time</structfield> is the server state during which
<command>postgres</command> should start the process; it can be one of
<literal>BgWorkerStart_PostmasterStart</literal> (start as soon as
<command>postgres</command> itself has finished its own initialization; processes
requesting this are not eligible for database connections),
<literal>BgWorkerStart_ConsistentState</literal> (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</literal> (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. Note that this setting only indicates
when the processes are to be started; they do not stop when a different state
is reached.
<structfield>bgw_start_time</structfield> spécifie l'état du serveur dans lequel
<command>postgres</command> devrait démarrer le processus&nbsp;; les valeurs possibles
sont <literal>BgWorkerStart_PostmasterStart</literal> (démarrer dès que
<command>postgres</command> lui-même a fini sa propre initialisation&nbsp;;
les processus réclamant celà ne sont pas éligibles à une connexion à la base de données),
<literal>BgWorkerStart_ConsistentState</literal> (démarrer dès qu'un état cohérent
a été atteint sur un serveur esclave en lecture seule, permettant aux processus de se
connecter aux bases et d'exécuter des requêtes en lecture seule), et
<literal>BgWorkerStart_RecoveryFinished</literal> (démarrer dès que le système
est entré dans un état de lecture-écriture normal). Notez que les deux dernières
valeurs sont équivalentes sur un serveur qui n'est pas un esclave en lecture seule.
Notez également que ces valeurs indiquent uniquement quand les processus doivent
être démarrés&nbsp;; ils ne s'arrêtent pas quand un état différent est atteint.
</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.
<structfield>bgw_restart_time</structfield> est un intervalle, en secondes,
que <command>postgres</command> doit attendre avant de redémarrer un
processus, si celui-ci a subi un arrêt brutal. Cet intervalle peut être une valeur
positive ou <literal>BGW_NEVER_RESTART</literal>, indiquant de ne pas redémarrer
le processus suite à un arrêt brutal.
</para>

<para>
<structfield>bgw_main</structfield> is a pointer to the function to run when
the process is started. This function must take a single argument of type
<type>void *</type> and return <type>void</type>.
<structfield>bgw_main_arg</structfield> will be 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.
<structfield>bgw_main</structfield> est un pointeur vers la fonction à lancer
quand le processus est démarré. Cette fonction doit prendre un unique argument
de type <type>void *</type> et retourner <type>void</type>.
<structfield>bgw_main_arg</structfield> lui sera passé comme unique argument.
Notez que la variable globale <literal>MyBgworkerEntry</literal> pointe vers
une copie de la structure <structname>BackgroundWorker</structname> passée
lors de l'enregistrement.
</para>

<para>
<structfield>bgw_sighup</structfield> and <structfield>bgw_sigterm</structfield> are
pointers to functions that will be installed as signal handlers for the new
process. If <structfield>bgw_sighup</structfield> is NULL, then <literal>SIG_IGN</literal>
is used; if <structfield>bgw_sigterm</structfield> is NULL, a handler is installed that
will terminate the process after logging a suitable message.
<structfield>bgw_sighup</structfield> et <structfield>bgw_sigterm</structfield> sont
des pointeurs vers des fonctions qui seront installées comme gestionnaires de
signal pour les nouveaux processus. Si <structfield>bgw_sighup</structfield>
vaut NULL, alors <literal>SIG_IGN</literal> est utilisé&nbsp;; si
<structfield>bgw_sigterm</structfield> vaut NULL, un gestionnaire est installé qui terminera
le processus après avoir tracé un message adéquat.
</para>

<para>Once running, the process can connect to a database by calling
<para>Une fois démarré, le processus peut se connecter à une base en appelant
<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</varname> is NULL,
the session is not connected to any particular database, but shared catalogs
can be accessed. If <varname>username</varname> is NULL, the process will run as
the superuser created during <command>initdb</command>.
BackgroundWorkerInitializeConnection can only be called once per background
process, it is not possible to switch databases.
Cela autorise le processus à exécuter des transactions et des requêtes en
utilisant l'interface <literal>SPI</literal>. Si <varname>dbname</varname> vaut
NULL, la session n'est pas connectée à une base en particulier, mais les
catalogues partagés peuvent être accédés. Si <varname>username</varname> vaut
NULL, le processus sera démarré avec le super utilisateur créé durant
<command>initdb</command>.
BackgroundWorkerInitializeConnection ne peut être appelé qu'une fois par
processus background, il n'est donc pas possible de changer de base de données.

</para>

<para>
Signals are initially blocked when control reaches the
<structfield>bgw_main</structfield> 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</function> and blocked by calling
Les signaux sont initialement bloqués jusqu'à ce que le contrôle atteigne
la fonction <structfield>bgw_main</structfield>, et doivent être débloqués
par elle&nbsp;; cela permet une personnalisation ultérieure des
gestionnaires de signaux du processus, si nécessaire. Les signaux peuvent
être débloqués dans le nouveau processus en appellant
<function>BackgroundWorkerUnblockSignals</function> et bloqués en appelant
<function>BackgroundWorkerBlockSignals</function>.
</para>

<para>
Background workers are expected to be continuously running; if they exit
cleanly, <command>postgres</command> will restart them immediately. Consider doing
interruptible sleep when they have nothing to do; 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.
Les background workers devraient tourner continuellement&nbsp;; s'ils terminent
proprement, <command>postgres</command> les redémarrera immédiatement.
Essayez d'utiliser des pauses interruptibles quand ils n'ont rien à faire&nbsp;;
cela peut être effectué en appelant <function>WaitLatch()</function>. Vérifiez
que le drapeau <literal>WL_POSTMASTER_DEATH</literal> est positionné lors de
l'appel à cette fonction, et vérifiez le code retour pour une sortie rapide
dans le cas d'urgence où <command>postgres</command> lui-même se termine.
</para>

<para>
The <filename>worker_spi</filename> contrib module contains a working example,
which demonstrates some useful techniques.
Le module contrib <filename>worker_spi</filename> contient un exemple
fonctionnel, qui démontre quelques techniques utiles.
</para>
</chapter>

0 comments on commit 5a3dc58

Please sign in to comment.