-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathbgworker.html
More file actions
379 lines (378 loc) · 37.1 KB
/
bgworker.html
File metadata and controls
379 lines (378 loc) · 37.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>第46章 バックグラウンドワーカープロセス</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-start-transaction.html" title="SPI_start_transaction" /><link rel="next" href="logicaldecoding.html" title="第47章 ロジカルデコーディング" /><meta name="viewport" content="width=device-width,initial-scale=1.0" /></head><body id="docContent" class="container-fluid col-10"><div class="other_version"><a href="https://www.postgresql.jp/document/">バージョンごとのドキュメント一覧</a></div><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="4" align="center"><a accesskey="h" href="index.html">PostgreSQL 18.3文書</a></th></tr><tr><td width="10%" align="left"></td><td width="10%" align="left"></td><td width="60%" align="center"><a href="server-programming.html" title="パート V. サーバプログラミング">パート V. サーバプログラミング</a></td><td width="20%" align="right"><div class="actions"><a class="issue" title="github" href="https://github.com/pgsql-jp/jpug-doc/issues/new?template=bug_report.yml&what-happened=version 18.3 : bgworker.html">誤訳等の報告
</a></div></td></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-start-transaction.html" title="SPI_start_transaction">前へ</a> </td><td width="10%" align="left"><a accesskey="u" href="server-programming.html" title="パート V. サーバプログラミング">上へ</a></td><td width="60%" align="center">第46章 バックグラウンドワーカープロセス</td><td width="20%" align="right"> <a accesskey="n" href="logicaldecoding.html" title="第47章 ロジカルデコーディング">次へ</a></td></tr></table><hr /></div><div class="chapter" id="BGWORKER"><div class="titlepage"><div><div><h2 class="title">第46章 バックグラウンドワーカープロセス</h2></div></div></div><span class="original">
<title>Background Worker Processes</title>
</span><a id="id-1.8.13.2" class="indexterm"></a><a id="id-1.8.13.3" class="indexterm"></a><p>
<span class="original">
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.
</span>
PostgreSQLはユーザ提供のコードを別のプロセスとして実行するように拡張できます。
このプロセスは<code class="command">postgres</code>によって起動、終了、監視され、サーバの状態に密接にリンクした寿命を持つことができます。
これらのプロセスは<span class="productname">PostgreSQL</span>の共有メモリ領域にアタッチされ、データベースの内部に接続するオプションを持ちます。
これらはまた、通常のクライアントに接続された実際のサーバプロセスのように複数のトランザクションを連続して実行できます。
また、アプリケーションは<span class="application">libpq</span>とリンクすることにより通常のクライアントアプリケーションのようにサーバに接続して動作できます。
</p><div class="warning"><h3 class="title">警告</h3><p>
<span class="original">
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.
</span>
バックグラウンドワーカーを使うにあたっては、堅牢性とセキュリティリスクを考慮しなくてはなりません。なぜならば、<code class="literal">C</code>言語で書かれており、データへのアクセスが制限されていないためです。
バックグラウンドワーカープロセスを含むモジュールを有効にしたいと思っている管理者は、細心の注意を払って実践してください。
バックグラウンドワーカープロセスの実行は、注意深く検査されたモジュールだけを許可する必要があります。
</p></div><p>
<span class="original">
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.
</span>
バックグラウンドワーカーは、モジュールを<code class="varname">shared_preload_libraries</code>に記すことによって、<span class="productname">PostgreSQL</span>スタート時に初期化できます。
バックグラウンドワーカーとして実行したいモジュールは、<code class="function">_PG_init()</code>関数から<code class="function">RegisterBackgroundWorker(<code class="type">BackgroundWorker</code> *<em class="parameter"><code>worker</code></em>)</code>を呼び出すことで登録できます。
バックグラウンドワーカーはシステム起動後も<code class="function">RegisterDynamicBackgroundWorker(<code class="type">BackgroundWorker</code> *<em class="parameter"><code>worker</code></em>, <code class="type">BackgroundWorkerHandle</code> **<em class="parameter"><code>handle</code></em>)</code>を呼び出すことによって開始できます。
postmasterプロセスからのみ呼び出すことができる<code class="function">RegisterBackgroundWorker</code>とは異なり、<code class="function">RegisterDynamicBackgroundWorker</code>は通常のバックエンドまたは他のバックグラウンドワーカーから呼び出す必要があります。
</p><p>
<span class="original">
The structure <structname>BackgroundWorker</structname> is defined thus:
</span>
<code class="structname">BackgroundWorker</code>の構造体は以下のように定義されます。
</p><pre class="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;
</pre><p>
</p><p>
<span class="original">
<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.)
</span>
<code class="structfield">bgw_name</code>や<code class="structfield">bgw_type</code>は、ログメッセージ、プロセス一覧、および同様の場面で使用される文字列です。
<code class="structfield">bgw_type</code>は、同じ種類のバックグラウンドワーカーで全て同じになるため、例えば同じ種類のワーカーをプロセス一覧でグループ化できます。
一方で<code class="structfield">bgw_name</code>は、特定のプロセスに関する追加情報を含むことができます。
（通常、<code class="structfield">bgw_name</code>の文字列は何らかの形で種類に関する情報を含んでいますが、必須であるというわけではありません。）
</p><p>
<span class="original">
<structfield>bgw_flags</structfield> is a bitwise-or'd bit mask indicating the
capabilities that the module wants. Possible values are:
</span>
<code class="structfield">bgw_flags</code>は、モジュールが要求する機能をOR演算したビットマスクです。可能な値は以下の通りです。
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">BGWORKER_SHMEM_ACCESS</code></span></dt><dd><p>
<a id="id-1.8.13.9.2.1.2.1.1" class="indexterm"></a>
<span class="original">
Requests shared memory access. This flag is required.
</span>
共有メモリへのアクセスを要求します。
このフラグは必須です。
</p></dd><dt><span class="term"><code class="literal">BGWORKER_BACKEND_DATABASE_CONNECTION</code></span></dt><dd><p>
<span class="original">
<indexterm><primary>BGWORKER_BACKEND_&zwsp;DATABASE_CONNECTION</primary></indexterm>
Requests the ability to establish a database connection through which it
can later run transactions and queries. A background worker using
<literal>BGWORKER_BACKEND_DATABASE_CONNECTION</literal> to connect to a
database must also attach shared memory using
<literal>BGWORKER_SHMEM_ACCESS</literal>, or worker start-up will fail.
</span>
<a id="id-1.8.13.9.2.2.2.1.1" class="indexterm"></a>
トランザクションや問い合わせの実行が出来るデータベース接続を要求します。
<code class="literal">BGWORKER_BACKEND_DATABASE_CONNECTION</code>を使用してデータベースに接続するバックグラウンドワーカーは<code class="literal">BGWORKER_SHMEM_ACCESS</code>を使用して共有メモリにアタッチしなければなりません。さもなければ起動時に失敗します。
</p></dd></dl></div><p>
</p><p>
<span class="original">
<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.
</span>
<code class="structfield">bgw_start_time</code>は、<code class="command">postgres</code>がプロセスを起動するべきタイミングを指定します。
そのタイミングは、以下のうちの１つです。
<code class="literal">BgWorkerStart_PostmasterStart</code>（<code class="command">postgres</code>自身が初期化を終えるとすぐに起動します。これを要求するプロセスはデータベース接続に望ましいものではありません）、
<code class="literal">BgWorkerStart_ConsistentState</code>（ホットスタンバイで一貫性のある状態に到達し、データベースに接続して参照のみの問い合わせが実行できるようになると起動します）、
<code class="literal">BgWorkerStart_RecoveryFinished</code>（システムが通常の参照/更新の問い合わせを実行できるようになると起動します）。
最後の２つの値は、ホットスタンバイでないサーバでは同等であることに注意してください。
この設定はいつプロセスが起動されるかを示すだけであることに注意してください。
これらのプロセスは、違う状態になったときに停止するわけではありません。
</p><p>
<span class="original">
<structfield>bgw_restart_time</structfield> is the interval, in seconds, that
<command>postgres</command> should wait before restarting the process in
the event that 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.
</span>
<code class="structfield">bgw_restart_time</code>は、万が一プロセスがクラッシュした場合に<code class="command">postgres</code>がそのプロセスを再起動するために待つ必要のある間隔を秒単位で指定します。
これは任意の正の値、またはクラッシュしても再起動させない場合に<code class="literal">BGW_NEVER_RESTART</code>を指定します。
</p><p>
<span class="original">
<structfield>bgw_library_name</structfield> is the name of a library in
which the initial entry point for the background worker should be sought.
The named library will be dynamically loaded by the worker process and
<structfield>bgw_function_name</structfield> will be used to identify the
function to be called. If calling a function in the core code, this must
be set to <literal>"postgres"</literal>.
</span>
<code class="structfield">bgw_library_name</code>は、バックグラウンドワーカーの初期エントリポイントのためのライブラリ名です。
その指定されたライブラリがワーカープロセスによって動的にロードされます。呼び出すべき関数を特定するために<code class="structfield">bgw_function_name</code>が使用されます。
コアコード内の関数を呼び出す場合、<code class="literal">"postgres"</code>を設定する必要があります。
</p><p>
<span class="original">
<structfield>bgw_function_name</structfield> is the name of the function
to use as the initial entry point for the new background worker. If
this function is in a dynamically loaded library, it must be marked
<literal>PGDLLEXPORT</literal> (and not <literal>static</literal>).
</span>
<code class="structfield">bgw_function_name</code>は、新しいバックグラウンドワーカーの初期エントリポイントとして使用する関数の名前です。
この関数が動的にロードされたライブラリ内にある場合、<code class="literal">PGDLLEXPORT</code>（<code class="literal">static</code>ではない）とマークする必要があります。
</p><p>
<span class="original">
<structfield>bgw_main_arg</structfield> is the <type>Datum</type> argument
to the background worker main function. This main function should take a
single argument of type <type>Datum</type> and return <type>void</type>.
<structfield>bgw_main_arg</structfield> will be passed as the argument.
In addition, the global variable <literal>MyBgworkerEntry</literal>
points to a copy of the <structname>BackgroundWorker</structname> structure
passed at registration time; the worker may find it helpful to examine
this structure.
</span>
<code class="structfield">bgw_main_arg</code>は、バックグラウンドワーカーのメイン関数の<code class="type">Datum</code>引数です。
メイン関数は単一の<code class="type">Datum</code>引数を取り、<code class="type">void</code>を返します。
<code class="structfield">bgw_main_arg</code>は引数として渡されます。
加えて、グローバル変数<code class="literal">MyBgworkerEntry</code>は、登録時に渡された<code class="structname">BackgroundWorker</code>構造体のコピーを指しています。
ワーカーはこの構造を調べることがあり、役に立ちます。
</p><p>
<span class="original">
On Windows (and anywhere else where <literal>EXEC_BACKEND</literal> is
defined) or in dynamic background workers it is not safe to pass a
<type>Datum</type> by reference, only by value. If an argument is required, it
is safest to pass an int32 or other small value and use that as an index
into an array allocated in shared memory. If a value like a <type>cstring</type>
or <type>text</type> is passed then the pointer won't be valid from the
new background worker process.
</span>
Windowsの（どこか他の場所で<code class="literal">EXEC_BACKEND</code>が定義されている）場合、または動的バックグラウンドワーカーは、<code class="type">Datum</code>を参照で渡すのは安全ではありません。値のみで渡してください。
引数が必要な場合は、int32型または他の小さな値を渡し、共有メモリに割り当てられた配列へのインデックスとしてそれを使用するのが最も安全です。
<code class="type">cstring</code>や<code class="type">text</code>のようなポインタを渡された場合は、新しいバックグラウンドワーカープロセスから有効になりません。
</p><p>
<span class="original">
<structfield>bgw_extra</structfield> can contain extra data to be passed
to the background worker. Unlike <structfield>bgw_main_arg</structfield>, this data
is not passed as an argument to the worker's main function, but it can be
accessed via <literal>MyBgworkerEntry</literal>, as discussed above.
</span>
<code class="structfield">bgw_extra</code>はバックグラウンドワーカーに渡す追加データを含めることが出来ます。
<code class="structfield">bgw_main_arg</code>とは異なり、このデータはワーカーのメイン関数の引数として渡されていませんが、上述したように<code class="literal">MyBgworkerEntry</code>を介してアクセスできます。
</p><p>
<span class="original">
<structfield>bgw_notify_pid</structfield> is the PID of a PostgreSQL
backend process to which the postmaster should send <literal>SIGUSR1</literal>
when the process is started or exits. It should be 0 for workers registered
at postmaster startup time, or when the backend registering the worker does
not wish to wait for the worker to start up. Otherwise, it should be
initialized to <literal>MyProcPid</literal>.
</span>
<code class="structfield">bgw_notify_pid</code>は、プロセスの開始時と終了時にpostmasterが<code class="literal">SIGUSR1</code>を送信するPostgreSQLバックエンドプロセスのPIDです。
それはpostmasterの起動時に登録されたワーカーの場合、またはワーカーを登録しているバックエンドがワーカーの起動を待ちたくない場合は0にする必要があります。
それ以外の場合は、<code class="literal">MyProcPid</code>で初期化する必要があります。
</p><span class="original">
<para>Once running, the process can connect to a database by calling
<function>BackgroundWorkerInitializeConnection(<parameter>char *dbname</parameter>, <parameter>char *username</parameter>, <parameter>uint32 flags</parameter>)</function> or
<function>BackgroundWorkerInitializeConnectionByOid(<parameter>Oid dboid</parameter>, <parameter>Oid useroid</parameter>, <parameter>uint32 flags</parameter>)</function>.
This allows the process to run transactions and queries using the
<literal>SPI</literal> interface. If <varname>dbname</varname> is NULL or
<varname>dboid</varname> is <literal>InvalidOid</literal>, the session is not connected
to any particular database, but shared catalogs can be accessed.
If <varname>username</varname> is NULL or <varname>useroid</varname> is
<literal>InvalidOid</literal>, the process will run as the superuser created
during <command>initdb</command>. If <literal>BGWORKER_BYPASS_ALLOWCONN</literal>
is specified as <varname>flags</varname> it is possible to bypass the restriction
to connect to databases not allowing user connections.
If <literal>BGWORKER_BYPASS_ROLELOGINCHECK</literal> is specified as
<varname>flags</varname> it is possible to bypass the login check for the
role used to connect to databases.
A background worker can only call one of these two functions, and only
once. It is not possible to switch databases.
</span><p>
ひとたび実行すると、このプロセスは<code class="function">BackgroundWorkerInitializeConnection(<em class="parameter"><code>char *dbname</code></em>, <em class="parameter"><code>char *username</code></em>, <em class="parameter"><code>uint32 flags</code></em>)</code>または<code class="function">BackgroundWorkerInitializeConnectionByOid(<em class="parameter"><code>Oid dboid</code></em>, <em class="parameter"><code>Oid useroid</code></em>, <em class="parameter"><code>uint32 flags</code></em>)</code>を呼び出すことによって、データベースに接続できます。
これにより、プロセスは<code class="literal">SPI</code>インタフェースを使用してトランザクションと問い合わせを実行できます。
もし、<code class="varname">dbname</code>がNULL、または<code class="varname">dboid</code>が<code class="literal">InvalidOid</code>である場合には、そのセッションは特定のデータベースに接続しません。しかし、共有カタログにはアクセス出来ます。
もし、<code class="varname">username</code>がNULL、または<code class="varname">useroid</code>が<code class="literal">InvalidOid</code>である場合には、そのプロセスは<code class="command">initdb</code>時に作成されたスーパーユーザとして実行されます。
<code class="varname">flags</code>として<code class="literal">BGWORKER_BYPASS_ALLOWCONN</code>が設定されている場合、ユーザ接続を許可しないデータベースへの接続制約を回避できます。
<code class="varname">flags</code>として<code class="literal">BGWORKER_BYPASS_ROLELOGINCHECK</code>が設定されている場合、データベースへの接続に使用されるロールのログインチェックを回避できます。
バックグラウンドワーカーはこれら２つの関数をどちらかを一度だけ呼ぶことが出来ます。
データベースを切り替えることができません。
</p><p>
<span class="original">
Signals are initially blocked when control reaches the
background worker's main function, and must be unblocked by it; this is to
allow the process to customize its signal handlers, if necessary.
Signals can be unblocked in the new process by calling
<function>BackgroundWorkerUnblockSignals</function> and blocked by calling
<function>BackgroundWorkerBlockSignals</function>.
</span>
バックグラウンドワーカーのメイン関数に制御が達したとき、シグナルは最初にブロックされています。このブロックは解除されなければなりません。
これは、必要に応じてプロセスがシグナルハンドラをカスタマイズできるようにするためです。
シグナルは、新しいプロセスで<code class="function">BackgroundWorkerUnblockSignals</code>を呼び出すことにより解除でき、<code class="function">BackgroundWorkerBlockSignals</code>を呼び出すことでブロックできます。
</p><p>
<span class="original">
If <structfield>bgw_restart_time</structfield> for a background worker is
configured as <literal>BGW_NEVER_RESTART</literal>, or if it exits with an exit
code of 0 or is terminated by <function>TerminateBackgroundWorker</function>,
it will be automatically unregistered by the postmaster on exit.
Otherwise, it will be restarted after the time period configured via
<structfield>bgw_restart_time</structfield>, or immediately if the postmaster
reinitializes the cluster due to a backend failure. Backends which need
to suspend execution only temporarily should use an interruptible sleep
rather than exiting; 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.
</span>
バックグラウンドワーカーは、<code class="structfield">bgw_restart_time</code>が<code class="literal">BGW_NEVER_RESTART</code>に設定されている場合、または終了コード0で終了した場合、または<code class="function">TerminateBackgroundWorker</code>によって終了した場合、postmasterに自動的に登録が解除されて終了します。
それ以外の場合、<code class="structfield">bgw_restart_time</code>で設定された時間の後に再起動します。または、バックエンドの障害のためにpostmasterがクラスタを再初期化した場合は、すぐに再起動します。
一時的に実行を中断するだけでよいバックエンドは、終了するのではなく、割り込み可能なスリープを使用する必要があります。
これは<code class="function">WaitLatch()</code>を呼び出すことによって可能になります。
この関数を呼び出すときには<code class="literal">WL_POSTMASTER_DEATH</code>フラグが設定されているか確認し、<code class="command">postgres</code>自身が終了する緊急事態には、リターンコードを確認するようにしてください。
</p><p>
<span class="original">
When a background worker is registered using the
<function>RegisterDynamicBackgroundWorker</function> function, it is
possible for the backend performing the registration to obtain information
regarding the status of the worker. Backends wishing to do this should
pass the address of a <type>BackgroundWorkerHandle *</type> as the second
argument to <function>RegisterDynamicBackgroundWorker</function>. If the
worker is successfully registered, this pointer will be initialized with an
opaque handle that can subsequently be passed to
<function>GetBackgroundWorkerPid(<parameter>BackgroundWorkerHandle *</parameter>, <parameter>pid_t *</parameter>)</function> or
<function>TerminateBackgroundWorker(<parameter>BackgroundWorkerHandle *</parameter>)</function>.
<function>GetBackgroundWorkerPid</function> can be used to poll the status of the
worker: a return value of <literal>BGWH_NOT_YET_STARTED</literal> indicates that
the worker has not yet been started by the postmaster;
<literal>BGWH_STOPPED</literal> indicates that it has been started but is
no longer running; and <literal>BGWH_STARTED</literal> indicates that it is
currently running. In this last case, the PID will also be returned via the
second argument.
<function>TerminateBackgroundWorker</function> causes the postmaster to send
<literal>SIGTERM</literal> to the worker if it is running, and to unregister it
as soon as it is not.
</span>
バックグラウンドワーカーを<code class="function">RegisterDynamicBackgroundWorker</code>関数により登録している場合、登録を実行するバックエンドはワーカーの状態に関する情報を取得することが可能です。
取得したい場合は<code class="function">RegisterDynamicBackgroundWorker</code>に2番目の引数として<code class="type">BackgroundWorkerHandle *</code>のアドレスを渡す必要があります。
もし登録に成功した場合、このポインタは後で<code class="function">GetBackgroundWorkerPid(<em class="parameter"><code>BackgroundWorkerHandle *</code></em>,<em class="parameter"><code>pid_t *</code></em>)</code>または<code class="function">TerminateBackgroundWorker(<em class="parameter"><code>BackgroundWorkerHandle *</code></em>)</code>に渡すことができるopaque(不透明)ハンドルで、初期化されます。
<code class="function">GetBackgroundWorkerPid</code>はワーカーの状態を監視できます。以下の戻り値が得られます。
<code class="literal">BGWH_NOT_YET_STARTED</code>ワーカーはまだpostmasterにより開始されていない。
<code class="literal">BGWH_STOPPED</code>開始されたが、もはや実行されていない。
<code class="literal">BGWH_STARTED</code>実行中です。
この最後のケースでは、PIDは、2番目の引数を介して返されます。
<code class="function">TerminateBackgroundWorker</code>はワーカーが実行していた場合postmasterがワーカーに<code class="literal">SIGTERM</code>を送信し、実行が終了次第すぐに登録を解除します。
</p><p>
<span class="original">
In some cases, a process which registers a background worker may wish to
wait for the worker to start up. This can be accomplished by initializing
<structfield>bgw_notify_pid</structfield> to <literal>MyProcPid</literal> and
then passing the <type>BackgroundWorkerHandle *</type> obtained at
registration time to
<function>WaitForBackgroundWorkerStartup(<parameter>BackgroundWorkerHandle
*handle</parameter>, <parameter>pid_t *</parameter>)</function> function.
This function will block until the postmaster has attempted to start the
background worker, or until the postmaster dies. If the background worker
is running, the return value will be <literal>BGWH_STARTED</literal>, and
the PID will be written to the provided address. Otherwise, the return
value will be <literal>BGWH_STOPPED</literal> or
<literal>BGWH_POSTMASTER_DIED</literal>.
</span>
場合によっては、バックグラウンドワーカーが起動するのを待ってから、ワーカーを登録したい場合もあるでしょう。
これは <code class="structfield">bgw_notify_pid</code>を<code class="literal">MyProcPid</code>で初期化し、登録時に得られた<code class="type">BackgroundWorkerHandle *</code>を使用して<code class="function">WaitForBackgroundWorkerStartup(<em class="parameter"><code>BackgroundWorkerHandle *handle</code></em>,<em class="parameter"><code>pid_t *</code></em>)</code>関数を呼び出すことで実現します。
postmasterがバックグラウンドワーカーを開始しようと試みたか、postmasterが死ぬまで、この関数はブロックします。
バックグラウンドワーカーが実行されている場合、戻り値は<code class="literal">BGWH_STARTED</code>となり、指定されたアドレスにPIDが書き込まれます。
そうでない場合、戻り値は<code class="literal">BGWH_STOPPED</code>または<code class="literal">BGWH_POSTMASTER_DIED</code>になります。
</p><p>
<span class="original">
A process can also wait for a background worker to shut down, by using the
<function>WaitForBackgroundWorkerShutdown(<parameter>BackgroundWorkerHandle
*handle</parameter>)</function> function and passing the
<type>BackgroundWorkerHandle *</type> obtained at registration. This
function will block until the background worker exits, or postmaster dies.
When the background worker exits, the return value is
<literal>BGWH_STOPPED</literal>, if postmaster dies it will return
<literal>BGWH_POSTMASTER_DIED</literal>.
</span>
登録時に得られた<code class="type">BackgroundWorkerHandle *</code>を使用して<code class="function">WaitForBackgroundWorkerShutdown(<em class="parameter"><code>BackgroundWorkerHandle *handle</code></em>)</code>関数を呼び出すことで、バックグラウンドワーカーがシャットダウンするのを待つこともできます。
バックグラウンドワーカーが終了するか、postmasterが死ぬまで、この関数はブロックします。
バックグラウンドワーカーが終了した場合の戻り値は<code class="literal">BGWH_STOPPED</code>、postmasterが死んだ場合の戻り値は<code class="literal">BGWH_POSTMASTER_DIED</code>になります。
</p><p>
<span class="original">
Background workers can send asynchronous notification messages, either by
using the <command>NOTIFY</command> command via <acronym>SPI</acronym>,
or directly via <function>Async_Notify()</function>. Such notifications
will be sent at transaction commit.
Background workers should not register to receive asynchronous
notifications with the <command>LISTEN</command> command, as there is no
infrastructure for a worker to consume such notifications.
</span>
バックグラウンドワーカーは、<acronym class="acronym">SPI</acronym>経由で<code class="command">NOTIFY</code>コマンドを使用して、あるいは<code class="function">Async_Notify()</code>で直接、非同期通知メッセージを送ることができます。
そのような通知はトランザクションのコミット時に送信されます。
バックグラウンドワーカーは、<code class="command">LISTEN</code>コマンドによる非同期通知メッセージの受信登録をすべきではありません。
ワーカーがそのような通知を消費する基盤が存在しないからです。
</p><p>
<span class="original">
The <filename>src/test/modules/worker_spi</filename> module
contains a working example,
which demonstrates some useful techniques.
</span>
バックグラウンドワーカーの実例として、<code class="filename">src/test/modules/worker_spi</code>というモジュールがあります。
これはいくつかの有用な技術を示しています。
</p><p>
<span class="original">
The maximum number of registered background workers is limited by
<xref linkend="guc-max-worker-processes"/>.
</span>
登録できるバックグラウンドワーカーの最大数は<a class="xref" href="runtime-config-resource.html#GUC-MAX-WORKER-PROCESSES">max_worker_processes</a>によって制限されています。
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-start-transaction.html" title="SPI_start_transaction">前へ</a> </td><td width="20%" align="center"><a accesskey="u" href="server-programming.html" title="パート V. サーバプログラミング">上へ</a></td><td width="40%" align="right"> <a accesskey="n" href="logicaldecoding.html" title="第47章 ロジカルデコーディング">次へ</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_start_transaction </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.3文書">ホーム</a></td><td width="40%" align="right" valign="top"> 第47章 ロジカルデコーディング</td></tr></table></div></body></html>