From 96ce89cb7e1a97d9d247fbacba73ade85a01ea38 Mon Sep 17 00:00:00 2001 From: Craig Ringer Date: Mon, 18 Jan 2021 14:05:15 +0800 Subject: [PATCH v1 2/2] Expand docs on PostgreSQL extension coding 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. --- doc/src/sgml/bgworker.sgml | 86 ++++++++++++++++++-- doc/src/sgml/xfunc.sgml | 162 ++++++++++++++++++++++++++++++++++++- 2 files changed, 239 insertions(+), 9 deletions(-) diff --git a/doc/src/sgml/bgworker.sgml b/doc/src/sgml/bgworker.sgml index 7fd673ab54..9216b8e0ea 100644 --- a/doc/src/sgml/bgworker.sgml +++ b/doc/src/sgml/bgworker.sgml @@ -1,6 +1,6 @@ - + Background Worker Processes @@ -29,6 +29,12 @@ + + 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 workers can be initialized at the time that PostgreSQL is started by including the module name in @@ -95,6 +101,11 @@ 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 + request extension shared memory allocations, LWLocks, + etc. + @@ -212,9 +223,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 +307,74 @@ 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 usleep(), + system(), make blocking system calls, etc. + + + + The 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 installed for background workers do + not interrupt queries or blocking calls into other postgres 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 bgworker + 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 install these handlers, before unblocking interrupts + run: + + 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 in the + postgres headers for more details on signal handling. + + + + diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index 2863f7c206..9ff1d003a9 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -2558,7 +2558,7 @@ CREATE FUNCTION concat_text(text, text) RETURNS text - + Writing Code @@ -2615,7 +2615,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. @@ -2659,6 +2660,163 @@ 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. + 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 + and should only use the main thread. PostgreSQL generally uses subprocesses + that coordinate over shared memory instead of threads - 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 case of a shutdown request, query cancel, etc. This means + you should 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 mid-execution + by PostgreSQL if any function that it calls makes a + CHECK_FOR_INTERRUPTS() check. It may not + get the opportunity to take cleanup actions via a + PG_TRY() ... PG_CATCH() + block if this happens. 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, + the 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. Details on all of these + is far outside the scope of this document, and the best reference is + the relevant source code. + + + + + + Sometimes relation-based state management for extensions is not + sufficient to meet their needs. 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. Others + can be found in various main PostgreSQL backend code. + + + + + + Look up system catalogs and table information 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 + any 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 subtle bugs. 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.29.2