37
37
<function>RegisterBackgroundWorker(<type>BackgroundWorker *worker</type>)</function>
38
38
from its <function>_PG_init()</>. Background workers can also be started
39
39
after the system is up and running by calling the function
40
- <function>RegisterDynamicBackgroundWorker</function> (<type>BackgroundWorker
41
- *worker</type>). Unlike < function>RegisterBackgroundWorker</>, which can
42
- only be called from within the postmaster,
43
- <function>RegisterDynamicBackgroundWorker</function> must be called from
44
- a regular backend.
40
+ <function>RegisterDynamicBackgroundWorker(<type>BackgroundWorker
41
+ *worker, BackgroundWorkerHandle **handle </type>)</ function>. Unlike
42
+ <function>RegisterBackgroundWorker</>, which can only be called from within
43
+ the postmaster, <function>RegisterDynamicBackgroundWorker</function> must be
44
+ called from a regular backend.
45
45
</para>
46
46
47
47
<para>
@@ -58,6 +58,7 @@ typedef struct BackgroundWorker
58
58
char bgw_library_name[BGW_MAXLEN]; /* only if bgw_main is NULL */
59
59
char bgw_function_name[BGW_MAXLEN]; /* only if bgw_main is NULL */
60
60
Datum bgw_main_arg;
61
+ int bgw_notify_pid;
61
62
} BackgroundWorker;
62
63
</programlisting>
63
64
</para>
@@ -135,6 +136,15 @@ typedef struct BackgroundWorker
135
136
<structfield>bgw_main</structfield> is NULL.
136
137
</para>
137
138
139
+ <para>
140
+ <structfield>bgw_notify_pid</structfield> is the PID of a PostgreSQL
141
+ backend process to which the postmaster should send <literal>SIGUSR1</>
142
+ when the process is started or exits. It should be 0 for workers registered
143
+ at postmaster startup time, or when the backend registering the worker does
144
+ not wish to wait for the worker to start up. Otherwise, it should be
145
+ initialized to <literal>MyProcPid</>.
146
+ </para>
147
+
138
148
<para>Once running, the process can connect to a database by calling
139
149
<function>BackgroundWorkerInitializeConnection(<parameter>char *dbname</parameter>, <parameter>char *username</parameter>)</function>.
140
150
This allows the process to run transactions and queries using the
@@ -165,6 +175,40 @@ typedef struct BackgroundWorker
165
175
<command>postgres</> itself has terminated.
166
176
</para>
167
177
178
+ <para>
179
+ When a background worker is registered using the
180
+ <function>RegisterDynamicBackgroundWorker</function> function, it is
181
+ possible for the backend performing the registration to obtain information
182
+ the status of the worker. Backends wishing to do this should pass the
183
+ address of a <type>BackgroundWorkerHandle *</type> as the second argument
184
+ to <function>RegisterDynamicBackgroundWorker</function>. If the worker
185
+ is successfully registered, this pointer will be initialized with an
186
+ opaque handle that can subsequently be passed to
187
+ <function>GetBackgroundWorkerPid(<parameter>BackgroundWorkerHandle *</parameter>, <parameter>pid_t *</parameter>)</function>.
188
+ This function can be used to poll the status of the worker: a return
189
+ value of <literal>BGWH_NOT_YET_STARTED</> indicates that the worker has not
190
+ yet been started by the postmaster; <literal>BGWH_STOPPED</literal>
191
+ indicates that it has been started but is no longer running; and
192
+ <literal>BGWH_STARTED</literal> indicates that it is currently running.
193
+ In this last case, the PID will also be returned via the second argument.
194
+ </para>
195
+
196
+ <para>
197
+ In some cases, a process which registers a background worker may wish to
198
+ wait for the worker to start up. This can be accomplished by initializing
199
+ <structfield>bgw_notify_pid</structfield> to <literal>MyProcPid</> and
200
+ then passing the <type>BackgroundWorkerHandle *</type> obtained at
201
+ registration time to
202
+ <function>WaitForBackgroundWorkerStartup(<parameter>BackgroundWorkerHandle
203
+ *handle</parameter>, <parameter>pid_t *</parameter>)</function> function.
204
+ This function will block until the postmaster has attempted to start the
205
+ background worker, or until the postmaster dies. If the background runner
206
+ is running, the return value will <literal>BGWH_STARTED</>, and
207
+ the PID will be written to the provided address. Otherwise, the return
208
+ value will be <literal>BGWH_STOPPED</literal> or
209
+ <literal>BGWH_POSTMASTER_DIED</literal>.
210
+ </para>
211
+
168
212
<para>
169
213
The <filename>worker_spi</> contrib module contains a working example,
170
214
which demonstrates some useful techniques.
0 commit comments