Presently, the archiver process restarts when an archive callback
ERRORs. To avoid this, archive module authors can use sigsetjmp(),
manage a memory context, etc., but that requires a lot of extra
code that will likely look roughly the same between modules. This
commit adds basic archive callback ERROR handling to pgarch.c so
that module authors won't ordinarily need to worry about this.
While this built-in handler attempts to clean up anything that an
archive module could conceivably have left behind, it is possible
that some modules are doing unexpected things that require
additional cleanup. Module authors should be sure to do any extra
required cleanup in a PG_CATCH block within the archiving callback.
The archiving callback is now called in a short-lived memory
context that the archiver process resets between invocations. If a
module requires longer-lived storage, it must maintain its own
memory context.
Thanks to these changes, the basic_archive module can be greatly
simplified.
Suggested-by: Andres Freund
Reviewed-by: Andres Freund, Yong Li
Discussion: https://postgr.es/m/20230217215624.GA3131134%40nathanxps13
<!-- doc/src/sgml/README.links -->
Linking within DocBook documents can be confusing, so here is a summary:
Intra-document Linking
----------------------
<xref>
use to get chapter/section number from the title of the target
link, or xreflabel if defined at the target, or refentrytitle if target
is a refentry; has no close tag
http://www.oasis-open.org/docbook/documentation/reference/html/xref.html
linkend=
controls the target of the link/xref, required
endterm=
for <xref>, allows the text of the link/xref to be taken from a
different link target title
<link>
use to supply text for the link, only uses linkend, requires </link>
http://www.oasis-open.org/docbook/documentation/reference/html/link.html
can be embedded inside of <command>, unlike <xref>
External Linking
----------------
<ulink>
like <link>, but uses a URL (not a document target); requires
</ulink>; if no text is specified, the URL appears as the link
text
http://www.oasis-open.org/docbook/documentation/reference/html/ulink.html
url=
used by <ulink> to specify the URL, required
Guidelines
----------
- For an internal link, if you want to supply text, use <link>, else
<xref>.
- Specific nouns like GUC variables, SQL commands, and contrib modules
usually have xreflabels.
- For an external link, use <ulink>, with or without link text.
- xreflabels added to tags prevent the chapter/section for id's from being
referenced; only the xreflabel is accessible. Therefore, use xreflabels
only when linking is common, and chapter/section information is unneeded.
c627d944e6