Sender: Daniel Gustafson <daniel.gustafson@gmail.com>
From: Daniel Gustafsson <daniel@yesql.se>
Content-Type: multipart/mixed;
 boundary="Apple-Mail=_583A1809-E55F-4B6C-B189-9056CEA0B160"
Subject: Document WaitForBackgroundWorkerShutdown and fix bgworker typo
Message-Id: <C8738949-0350-4999-A1DA-26E209FF248D@yesql.se>
Date: Fri, 9 Feb 2018 23:43:26 +0100
To: pgsql-docs <pgsql-docs@postgresql.org>
Mime-Version: 1.0 (Mac OS X Mail 9.3 \(3124\))
Precedence: bulk


--Apple-Mail=_583A1809-E55F-4B6C-B189-9056CEA0B160
Content-Transfer-Encoding: 7bit
Content-Type: text/plain;
	charset=us-ascii

WaitForBackgroundWorkerShutdown() was added in 924bcf4f16d, but never
documented which seems like an oversight for such a useful function.  The
attached patch adds this to bgworker.sgml, and also fixes what I believe are
typos in the WaitForBackgroundWorkerStartup paragraph.

cheers ./daniel


--Apple-Mail=_583A1809-E55F-4B6C-B189-9056CEA0B160
Content-Disposition: attachment;
	filename=bgworker.patch
Content-Type: application/octet-stream;
	name="bgworker.patch"
Content-Transfer-Encoding: quoted-printable

=46rom=202a67096e1f55b8f5489d6865c7ec3c86771500b4=20Mon=20Sep=2017=20=
00:00:00=202001=0AFrom:=20Daniel=20Gustafsson=20<daniel@yesql.se>=0A=
Date:=20Fri,=209=20Feb=202018=2023:22:02=20+0100=0ASubject:=20[PATCH]=20=
doc:=20Add=20WaitForBackgroundWorkerShutdown()=20to=20bgw=20docs=0A=0A=
Commit=20924bcf4f16d=20extended=20the=20background=20worker=20API=20with=0A=
WaitForBackgroundWorkerShutdown,=20but=20it=20was=20never=20added=20to=20=
the=0Adocumentation.=20Extend=20the=20bgworker=20docs,=20and=20also=20=
fix=20two=20small=0Aspelling=20errors=20in=20the=20=
WaitForBackgroundWorkerStartup=20paragraph.=0A---=0A=20=
doc/src/sgml/bgworker.sgml=20|=2015=20+++++++++++++--=0A=201=20file=20=
changed,=2013=20insertions(+),=202=20deletions(-)=0A=0Adiff=20--git=20=
a/doc/src/sgml/bgworker.sgml=20b/doc/src/sgml/bgworker.sgml=0Aindex=20=
e490bb8750..099639964c=20100644=0A---=20a/doc/src/sgml/bgworker.sgml=0A=
+++=20b/doc/src/sgml/bgworker.sgml=0A@@=20-259,13=20+259,24=20@@=20=
typedef=20struct=20BackgroundWorker=0A=20=20=20=20=
<function>WaitForBackgroundWorkerStartup(<parameter>BackgroundWorkerHandle=
=0A=20=20=20=20*handle</parameter>,=20<parameter>pid_t=20=
*</parameter>)</function>=20function.=0A=20=20=20=20This=20function=20=
will=20block=20until=20the=20postmaster=20has=20attempted=20to=20start=20=
the=0A-=20=20=20background=20worker,=20or=20until=20the=20postmaster=20=
dies.=20=20If=20the=20background=20runner=0A-=20=20=20is=20running,=20=
the=20return=20value=20will=20<literal>BGWH_STARTED</literal>,=20and=0A+=20=
=20=20background=20worker,=20or=20until=20the=20postmaster=20dies.=20=20=
If=20the=20background=20worker=0A+=20=20=20is=20running,=20the=20return=20=
value=20will=20be=20<literal>BGWH_STARTED</literal>,=20and=0A=20=20=20=20=
the=20PID=20will=20be=20written=20to=20the=20provided=20address.=20=20=
Otherwise,=20the=20return=0A=20=20=20=20value=20will=20be=20=
<literal>BGWH_STOPPED</literal>=20or=0A=20=20=20=20=
<literal>BGWH_POSTMASTER_DIED</literal>.=0A=20=20=20</para>=0A=20=0A+=20=20=
<para>=0A+=20=20=20A=20process=20can=20also=20wait=20for=20a=20=
background=20worker=20to=20shut=20down,=20by=20using=20the=0A+=20=20=20=
<function>WaitForBackgroundWorkerShutdown(<parameter>BackgroundWorkerHandl=
e=0A+=20=20=20*handle</parameter>)</function>=20function=20and=20pass=20=
the=0A+=20=20=20<type>BackgroundWorkerHandle=20*</type>=20obtained=20at=20=
registration.=20This=0A+=20=20=20function=20will=20block=20until=20the=20=
background=20worker=20exits,=20or=20the=20postmaster=0A+=20=20=20dies.=20=
=20When=20the=20background=20worker=20exits,=20the=20return=20value=20is=0A=
+=20=20=20<literal>BGWH_STOPPED</literal>,=20if=20the=20postmaster=20=
dies=20it=20will=20return=0A+=20=20=20=
<literal>BGWH_POSTMASTER_DIED</literal>.=0A+=20=20</para>=0A+=0A=20=20=20=
<para>=0A=20=20=20=20If=20a=20background=20worker=20sends=20asynchronous=20=
notifications=20with=20the=0A=20=20=20=20<command>NOTIFY</command>=20=
command=20via=20the=20Server=20Programming=20Interface=0A--=20=0A=
2.14.1.145.gb3622a4ee=0A=0A=

--Apple-Mail=_583A1809-E55F-4B6C-B189-9056CEA0B160--