From 9c3f7b19ab8364cf151ca8b053150d29d37c390c Mon Sep 17 00:00:00 2001 From: Laurenz Albe Date: Sun, 30 May 2021 13:15:55 +0200 Subject: [PATCH] Expand the docs on PostgreSQL extension coding and background worker development a little so that key topics like allocation, interrupt handling, exit callbacks, transaction callbacks, PG_TRY()/PG_CATCH(), resource owners, transaction and snapshot state, etc are at least briefly mentioned with a few pointers to where to learn more. Add some detail on background worker signal handling. Author: Craig Ringer Reviewed-By: Laurenz Albe, Bharath Rupireddy Discussion: https://postgr.es/m/CAGRY4nxanz6MQrOv_babTjg02VwcXkq+eBsQhqdFX6-PgTapDQ@mail.gmail.com --- doc/src/sgml/bgworker.sgml | 94 +++++++++++++++++++-- doc/src/sgml/xfunc.sgml | 163 ++++++++++++++++++++++++++++++++++++- 2 files changed, 248 insertions(+), 9 deletions(-) diff --git a/doc/src/sgml/bgworker.sgml b/doc/src/sgml/bgworker.sgml index 7fd673ab54..a99d048ed1 100644 --- a/doc/src/sgml/bgworker.sgml +++ b/doc/src/sgml/bgworker.sgml @@ -1,6 +1,6 @@ - + Background Worker Processes @@ -29,6 +29,15 @@ + + All code that will be executed in PostgreSQL background workers is expected + to follow the basic rules set out for all PostgreSQL extension code in . + + + + Background Worker initialization and resource allocation + Background workers can be initialized at the time that PostgreSQL is started by including the module name in @@ -95,6 +104,10 @@ typedef struct BackgroundWorker buffers, or any custom data structures which the worker itself may wish to create and use. + + See for information on how to + allocate these resources. + @@ -212,9 +225,9 @@ typedef struct BackgroundWorker 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 - BackgroundWorkerUnblockSignals and blocked by calling - BackgroundWorkerBlockSignals. + It is important that all background workers set up and unblock signal + handling before they enter their main loops. Signal handling in background + workers is discussed separately in . @@ -296,13 +309,80 @@ typedef struct BackgroundWorker - The src/test/modules/worker_spi module - contains a working example, - which demonstrates some useful techniques. + Background workers that require inter-process communication and/or + synchronisation should use PostgreSQL's built-in + IPC and concurrency features as discussed in + and + . + + + + If a background worker needs to sleep or wait for activity, it should + always use + PostgreSQL's + interupt-aware APIs for the purpose. Do not use + usleep(), system() or other + blocking system calls. + + + + The modules src/test/modules/worker_spi and + src/test/modules/test_shm_mq contain working examples + that demonstrates some useful techniques. The maximum number of registered background workers is limited by . + + + + + Signal Handling in Background Workers + + + Signals can be unblocked in the new process by calling + BackgroundWorkerUnblockSignals and blocked by calling + BackgroundWorkerBlockSignals. + The default signal handlers set up for background workers + do not interrupt queries or blocking calls into other + PostgreSQL code + so they are only suitable for simple background workers that frequently and + predictably return control to their main loop. If your worker uses the + default background worker signal handling, it should call + HandleMainLoopInterrupts() on each pass through its + main loop. + + + + Background workers that may make blocking calls into core + PostgreSQL code and/or run user-supplied queries + should generally replace the default background worker signal handlers with the + handlers used for normal user backends. This will ensure that the worker will + respond in a timely manner to a termination request, query cancel request, + recovery conflict interrupt, deadlock detector request, etc. + To set up these handlers, run the following before unblocking interrupts: + + pqsignal(SIGTERM, die); + pqsignal(SIGUSR1, procsignal_sigusr1_handler); + pqsignal(SIGHUP, SignalHandlerForConfigReload); + + Then ensure that your main loop and any other code that could run for some + time contains CHECK_FOR_INTERRUPTS() calls. + A background worker using these signal handlers must use PostgreSQL's + resource management APIs and callbacks to handle cleanup rather + than relying on control returning to the main loop, because the signal + handlers may call proc_exit() directly. + This is recommended practice for all types of extension code anyway. + + + + See the comments in src/include/miscadmin.h + for more details on signal handling. + + + + diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index 41bcc5b79d..cc79871f04 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -2593,7 +2593,7 @@ CREATE FUNCTION concat_text(text, text) RETURNS text - + Writing Code @@ -2650,7 +2650,8 @@ CREATE FUNCTION concat_text(text, text) RETURNS text malloc and free. The memory allocated by palloc will be freed automatically at the end of each transaction, preventing - memory leaks. + memory leaks. See src/backend/utils/mmgr/README + for more details on PostgreSQL's memory management. @@ -2694,6 +2695,164 @@ CREATE FUNCTION concat_text(text, text) RETURNS text error messages to this effect. + + + + Use elog() and ereport() for + logging output and raising errors instead of any direct stdio calls. + Do not attempt to use C++ exceptions or Windows Structured Exception + Handling, and never call exit() directly + (for a discussion of extensions in C++, see ). + PostgreSQL uses its own longjmp() based + exception system for ERROR-level elog() + and ereport() calls. These can be handled and forwarded with + PG_TRY() and PG_RE_THROW(): + + PG_TRY(); + { + ... + } + PG_CATCH(); + { + .... + /* Do not attempt to swallow the exception, always rethrow */ + PG_RE_THROW(); + } + PG_END_TRY(); + + See src/include/utils/elog.h and + src/backend/utils/error/elog.c for details. + + + + + + Individual PostgreSQL backends are single-threaded. + Never call any PostgreSQL function or access any + PostgreSQL-managed data structure from a thread + other than the main thread. If at all possible, your extension should not + start any threads. PostgreSQL generally uses + subprocesses (see ). + + + + + + To execute subprocesses and open files, use the routines provided by + the file descriptor manager like BasicOpenFile + and OpenPipeStream instead of a direct + open(), fopen(), + popen() or system(). + See src/include/storage/fd.h. + + + + + + Extension code should always be structured as a non-blocking + loop over any ongoing external activities. Avoid making blocking calls + into 3rd party libraries or uninterruptible + system calls. Use PostgreSQL's provided wait + primitives like WaitEventSetWait where necessary. Any + potentially long-running loop should periodically call + CHECK_FOR_INTERRUPTS() to give PostgreSQL + a chance to interrupt the function in the case of events like a shutdown + request or query cancellation. + This means that you should nor use sleep() or + usleep() for any nontrivial amount of time — + use WaitLatch() or its variants instead. + For details on interrupt handling, see comments near the definition of the + CHECK_FOR_INTERRUPTS() macro in + src/include/util/miscadmin.h. + + + + + + Use PostgreSQL's resource tracking and + registration mechanisms and the associated callbacks instead of relying + on flow control based cleanup. Your extension function could be terminated + in mid-execution by PostgreSQL if any function + that it calls performs a CHECK_FOR_INTERRUPTS() check. + If this happens, it may not get the opportunity to take cleanup actions + via a PG_TRY() ... PG_CATCH() + block. So all cleanup of resources not already managed by the + PostgreSQL runtime must be handled using + appropriate callbacks provided by PostgreSQL. + These include, but are not limited to, these callback registration APIs: + + before_shmem_exit() + on_shmem_exit() + on_proc_exit() + PG_ENSURE_ERROR_CLEANUP() + RegisterXactCallback() + RegisterResourceReleaseCallback() + + More information on resource management, cleanup and lifecycle can be + found in the PostgreSQL headers and sources. + + + + + + Use the PostgreSQL runtime's concurrency and + synchronisation primitives rather than platform-native primitives when + coordinating activity between PostgreSQL processes. + These include signals and ProcSignal multiplexed signals, + heavyweight locks ("normal" database object locks), + LWLocks, Spinlocks, latches, + condition variables, and more. + + + + + + Sometimes, relation-based state management is not sufficient to meet the + needs of an extension. In that case, the extension may need to use + PostgreSQL's shared-memory based inter-process + communication features, and should certainly do so instead of inventing + its own or trying to use platform level features. An extension may use + "raw" shared memory requested from + the postmaster at startup or higher level features like dynamic + shared memory segments (DSM), + dynamic shared areas (DSA), + or shared memory message queues (shm_mq). + Examples of the use of some these features can be found in the + src/test/modules/test_shm_mq/ example extension + or other parts of the source code. + + + + + + Look up system catalogs and table metadata using the relcache and syscache + APIs (SearchSysCache..., + relation_open(), etc) rather than attempting to run + SQL queries to fetch the information. Ensure that your function holds + the necessary locks on the target objects. Take care not to make any calls + that could trigger cache invalidations while still accessing any + syscache cache entries, as this can cause bugs that are hard to find. + See src/backend/utils/cache/syscache.c, + src/backend/utils/cache/relcache.c, + src/backend/access/common/relation.c and their + headers for details. + + + + + + There are many README files in the PostgreSQL + source tree that discuss specific development topics in more detail than + be covered here. Many subsystems' source files also have detailed comments + that explain their correct use. + The existing sources are your best reference for more complex tasks. + + + -- 2.26.3