From 4f7a0627eb0735874b53c90576243f8003a64b4a Mon Sep 17 00:00:00 2001 From: Michael Paquier Date: Wed, 25 Oct 2023 10:24:28 +0900 Subject: [PATCH 1/2] Base facility for injection points Extension and backend developers can register custom callbacks that would be run on a user-defined fashion. This is hidden behind a ./configure and a meson switch, disabled by default. --- src/include/pg_config.h.in | 3 + src/include/utils/injection_point.h | 35 ++++ src/backend/storage/ipc/ipci.c | 3 + src/backend/storage/lmgr/lwlocknames.txt | 1 + .../utils/activity/wait_event_names.txt | 1 + src/backend/utils/misc/Makefile | 1 + src/backend/utils/misc/injection_point.c | 158 ++++++++++++++++++ src/backend/utils/misc/meson.build | 1 + doc/src/sgml/installation.sgml | 30 ++++ doc/src/sgml/xfunc.sgml | 53 ++++++ configure | 32 ++++ configure.ac | 6 + meson.build | 1 + meson_options.txt | 3 + src/tools/pgindent/typedefs.list | 1 + 15 files changed, 329 insertions(+) create mode 100644 src/include/utils/injection_point.h create mode 100644 src/backend/utils/misc/injection_point.c diff --git a/src/include/pg_config.h.in b/src/include/pg_config.h.in index d8a2985567f..7a976821e55 100644 --- a/src/include/pg_config.h.in +++ b/src/include/pg_config.h.in @@ -701,6 +701,9 @@ /* Define to build with ICU support. (--with-icu) */ #undef USE_ICU +/* Define to 1 to build with injection points. (--enable-injection-points) */ +#undef USE_INJECTION_POINTS + /* Define to 1 to build with LDAP support. (--with-ldap) */ #undef USE_LDAP diff --git a/src/include/utils/injection_point.h b/src/include/utils/injection_point.h new file mode 100644 index 00000000000..3edc80fb8fe --- /dev/null +++ b/src/include/utils/injection_point.h @@ -0,0 +1,35 @@ +/*------------------------------------------------------------------------- + * injection_point.h + * Definitions related to injection points. + * + * Copyright (c) 2001-2023, PostgreSQL Global Development Group + * + * src/include/utils/injection_point.h + * ---------- + */ +#ifndef INJECTION_POINT_H +#define INJECTION_POINT_H + +/* + * Typedef for callback function launched by an injection point. + */ +typedef void (*InjectionPointCallback) (const char *name); + +/* + * Injections points require --enable-injection-points. + */ +#ifdef USE_INJECTION_POINTS +#define INJECTION_POINT_RUN(name) InjectionPointRun(name) +#else +#define INJECTION_POINT_RUN(name) +#endif + +extern Size InjectionPointShmemSize(void); +extern void InjectionPointShmemInit(void); + +extern void InjectionPointCreate(const char *name, + InjectionPointCallback callback); +extern void InjectionPointRun(const char *name); +extern void InjectionPointDrop(const char *name); + +#endif /* INJECTION_POINT_H */ diff --git a/src/backend/storage/ipc/ipci.c b/src/backend/storage/ipc/ipci.c index a3d8eacb8dc..12b8a42fd9b 100644 --- a/src/backend/storage/ipc/ipci.c +++ b/src/backend/storage/ipc/ipci.c @@ -48,6 +48,7 @@ #include "storage/sinvaladt.h" #include "storage/spin.h" #include "utils/guc.h" +#include "utils/injection_point.h" #include "utils/snapmgr.h" #include "utils/wait_event.h" @@ -143,6 +144,7 @@ CalculateShmemSize(int *num_semaphores) size = add_size(size, AsyncShmemSize()); size = add_size(size, StatsShmemSize()); size = add_size(size, WaitEventExtensionShmemSize()); + size = add_size(size, InjectionPointShmemSize()); #ifdef EXEC_BACKEND size = add_size(size, ShmemBackendArraySize()); #endif @@ -302,6 +304,7 @@ CreateSharedMemoryAndSemaphores(void) AsyncShmemInit(); StatsShmemInit(); WaitEventExtensionShmemInit(); + InjectionPointShmemInit(); #ifdef EXEC_BACKEND diff --git a/src/backend/storage/lmgr/lwlocknames.txt b/src/backend/storage/lmgr/lwlocknames.txt index f72f2906cea..42a048746df 100644 --- a/src/backend/storage/lmgr/lwlocknames.txt +++ b/src/backend/storage/lmgr/lwlocknames.txt @@ -54,3 +54,4 @@ XactTruncationLock 44 WrapLimitsVacuumLock 46 NotifyQueueTailLock 47 WaitEventExtensionLock 48 +InjectionPointLock 49 diff --git a/src/backend/utils/activity/wait_event_names.txt b/src/backend/utils/activity/wait_event_names.txt index d7995931bd4..5631d291383 100644 --- a/src/backend/utils/activity/wait_event_names.txt +++ b/src/backend/utils/activity/wait_event_names.txt @@ -319,6 +319,7 @@ XactTruncation "Waiting to execute pg_xact_status or update WrapLimitsVacuum "Waiting to update limits on transaction id and multixact consumption." NotifyQueueTail "Waiting to update limit on NOTIFY message storage." WaitEventExtension "Waiting to read or update custom wait events information for extensions." +InjectionPoint "Waiting to read or update information related to injection points." XactBuffer "Waiting for I/O on a transaction status SLRU buffer." CommitTsBuffer "Waiting for I/O on a commit timestamp SLRU buffer." diff --git a/src/backend/utils/misc/Makefile b/src/backend/utils/misc/Makefile index 29100329300..f0203501d12 100644 --- a/src/backend/utils/misc/Makefile +++ b/src/backend/utils/misc/Makefile @@ -21,6 +21,7 @@ OBJS = \ guc_funcs.o \ guc_tables.o \ help_config.o \ + injection_point.o \ pg_config.o \ pg_controldata.o \ pg_rusage.o \ diff --git a/src/backend/utils/misc/injection_point.c b/src/backend/utils/misc/injection_point.c new file mode 100644 index 00000000000..b9701fbb3a6 --- /dev/null +++ b/src/backend/utils/misc/injection_point.c @@ -0,0 +1,158 @@ +/*------------------------------------------------------------------------- + * + * injection_point.c + * Routines to control and run injection points in the code. + * + * Injection points can be used to call arbitrary callbacks in specific + * places of the code, registering callbacks that would be run in the code + * paths where a named injection point exists. + * + * Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group + * Portions Copyright (c) 1994, Regents of the University of California + * + * + * IDENTIFICATION + * src/backend/utils/misc/injection_point.c + * + *------------------------------------------------------------------------- + */ +#include "postgres.h" + +#include "miscadmin.h" +#include "storage/lwlock.h" +#include "storage/shmem.h" +#include "utils/hsearch.h" +#include "utils/injection_point.h" + +/* + * Hash table for storing injection points. + * + * InjectionPointHashByName is used to find an injection point by name. + */ +static HTAB *InjectionPointHashByName; /* find points from names */ + +/* Field sizes */ +#define INJ_MAXLEN 64 + +typedef struct InjectionPointEntryByName +{ + char name[INJ_MAXLEN]; /* hash key */ + InjectionPointCallback callback; +} InjectionPointEntryByName; + +#define INJECTION_POINT_HASH_INIT_SIZE 16 +#define INJECTION_POINT_HASH_MAX_SIZE 128 + +/* + * Return the space for dynamic shared hash table. + */ +Size +InjectionPointShmemSize(void) +{ +#ifdef USE_INJECTION_POINTS + Size sz = 0; + + sz = add_size(sz, hash_estimate_size(INJECTION_POINT_HASH_MAX_SIZE, + sizeof(InjectionPointEntryByName))); + return sz; +#endif +} + +/* + * Allocate shmem space for dynamic shared hash. + */ +void +InjectionPointShmemInit(void) +{ +#ifdef USE_INJECTION_POINTS + HASHCTL info; + + /* key is a NULL-terminated string */ + info.keysize = sizeof(char[INJ_MAXLEN]); + info.entrysize = sizeof(InjectionPointEntryByName); + InjectionPointHashByName = ShmemInitHash("InjectionPoint hash by name", + INJECTION_POINT_HASH_INIT_SIZE, + INJECTION_POINT_HASH_MAX_SIZE, + &info, + HASH_ELEM | HASH_STRINGS); +#endif +} + +/* + * Insert a new injection point. + */ +void +InjectionPointCreate(const char *name, InjectionPointCallback callback) +{ +#ifdef USE_INJECTION_POINTS + InjectionPointEntryByName *entry_by_name; + bool found; + + if (strlen(name) >= INJ_MAXLEN) + elog(ERROR, "injection point name %s too long", name); + + /* + * Allocate and register a new injection point. A new point should not + * exist. For testing purposes this should be fine. + */ + LWLockAcquire(InjectionPointLock, LW_EXCLUSIVE); + entry_by_name = (InjectionPointEntryByName *) + hash_search(InjectionPointHashByName, name, + HASH_ENTER, &found); + if (found) + { + LWLockRelease(InjectionPointLock); + elog(ERROR, "injection point \"%s\" already defined", name); + } + + /* Save the entry */ + memcpy(entry_by_name->name, name, sizeof(entry_by_name->name)); + entry_by_name->name[INJ_MAXLEN - 1] = '\0'; + entry_by_name->callback = callback; + + LWLockRelease(InjectionPointLock); +#else + elog(ERROR, "Injection points are not supported by this build"); +#endif +} + +void +InjectionPointDrop(const char *name) +{ +#ifdef USE_INJECTION_POINTS + bool found; + + LWLockAcquire(InjectionPointLock, LW_EXCLUSIVE); + hash_search(InjectionPointHashByName, name, HASH_REMOVE, &found); + LWLockRelease(InjectionPointLock); + + if (!found) + elog(ERROR, "injection point \"%s\" not found", name); +#else + elog(ERROR, "Injection points are not supported by this build"); +#endif +} + +void +InjectionPointRun(const char *name) +{ +#ifdef USE_INJECTION_POINTS + InjectionPointEntryByName *entry_by_name; + bool found; + + LWLockAcquire(InjectionPointLock, LW_SHARED); + entry_by_name = (InjectionPointEntryByName *) + hash_search(InjectionPointHashByName, name, + HASH_FIND, &found); + LWLockRelease(InjectionPointLock); + + /* If not found, do nothing? */ + if (!found) + return; + + /* Found, so just run the callback registered */ + entry_by_name->callback(entry_by_name->name); +#else + elog(ERROR, "Injection points are not supported by this build"); +#endif +} diff --git a/src/backend/utils/misc/meson.build b/src/backend/utils/misc/meson.build index f719c97c051..1438859b695 100644 --- a/src/backend/utils/misc/meson.build +++ b/src/backend/utils/misc/meson.build @@ -6,6 +6,7 @@ backend_sources += files( 'guc_funcs.c', 'guc_tables.c', 'help_config.c', + 'injection_point.c', 'pg_config.c', 'pg_controldata.c', 'pg_rusage.c', diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index 9b25e9fdb1b..ba055ad4a54 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -1677,6 +1677,21 @@ build-postgresql: + + + + + Compiles PostgreSQL with support for + injection points in the server. This is valuable to inject + user-defined code to force specific conditions to happen on the + server in pre-defined code paths. This option is disabled by default. + See for more details. + This option is only for developers to test specific concurrency + scenarios. + + + + @@ -3174,6 +3189,21 @@ ninja install + + + + + Compiles PostgreSQL with support for + injection points in the server. This is valuable to inject + user-defined code to force specific conditions to happen on the + server in pre-defined code paths. This option is disabled by default. + See for more details. + This option is only for developers to test specific concurrency + scenarios. + + + + diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index 96ba95818c2..e8dd262152e 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -3480,6 +3480,59 @@ uint32 WaitEventExtensionNew(const char *wait_event_name) + + Injection Points + + + Add-ins can define injection points, that can register callbacks + to run user-defined code when going through a specific code path, + by calling: + +extern void InjectionPointCreate(const char *name, + InjectionPointCallback callback); + + + name is the name of the injection point. + Injection points are saved in a hash table in shared memory, and + last until the server is shut down. + + + + Here is an example of callback for + InjectionPointCallback: + +static void +custom_injection_callback(const char *name) +{ + elog(NOTICE, "%s: executed custom callback", name); +} + + + + + Once an injection point is defined, running it requires to use + the following macro to trigger the callback given in a wanted code + path: + +INJECTION_POINT_RUN(name); + + + + + Optionally, it is possible to drop injection points by calling: + +extern void InjectionPointDrop(const char *name); + + + + + Enabling injections points requires + from + configure or + from Meson. + + + Using C++ for Extensibility diff --git a/configure b/configure index cfd968235f7..25ed062ce1f 100755 --- a/configure +++ b/configure @@ -839,6 +839,7 @@ enable_profiling enable_coverage enable_dtrace enable_tap_tests +enable_injection_points with_blocksize with_segsize with_segsize_blocks @@ -1532,6 +1533,8 @@ Optional Features: --enable-coverage build with coverage testing instrumentation --enable-dtrace build with DTrace support --enable-tap-tests enable TAP tests (requires Perl and IPC::Run) + --enable-injection-points + enable injection points (for testing) --enable-depend turn on automatic dependency tracking --enable-cassert enable assertion checks (for debugging) --disable-largefile omit support for large files @@ -3682,6 +3685,35 @@ fi +# +# Injection points +# + + +# Check whether --enable-injection-points was given. +if test "${enable_injection_points+set}" = set; then : + enableval=$enable_injection_points; + case $enableval in + yes) + +$as_echo "#define USE_INJECTION_POINTS 1" >>confdefs.h + + ;; + no) + : + ;; + *) + as_fn_error $? "no argument expected for --enable-injection-points option" "$LINENO" 5 + ;; + esac + +else + enable_injection_points=no + +fi + + + # # Block size # diff --git a/configure.ac b/configure.ac index f220b379b30..d9c734cf135 100644 --- a/configure.ac +++ b/configure.ac @@ -250,6 +250,12 @@ PGAC_ARG_BOOL(enable, tap-tests, no, [enable TAP tests (requires Perl and IPC::Run)]) AC_SUBST(enable_tap_tests) +# +# Injection points +# +PGAC_ARG_BOOL(enable, injection-points, no, [enable injection points (for testing)], + [AC_DEFINE([USE_INJECTION_POINTS], 1, [Define to 1 to build with injection points. (--enable-injection-points)])]) + # # Block size # diff --git a/meson.build b/meson.build index 2d516c8f372..232bc87e30b 100644 --- a/meson.build +++ b/meson.build @@ -431,6 +431,7 @@ meson_bin = find_program(meson_binpath, native: true) ############################################################### cdata.set('USE_ASSERT_CHECKING', get_option('cassert') ? 1 : false) +cdata.set('USE_INJECTION_POINTS', get_option('injection_points') ? 1 : false) blocksize = get_option('blocksize').to_int() * 1024 diff --git a/meson_options.txt b/meson_options.txt index d2f95cfec36..6041ab65410 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -43,6 +43,9 @@ option('cassert', type: 'boolean', value: false, option('tap_tests', type: 'feature', value: 'auto', description: 'Enable TAP tests') +option('injection_points', type: 'boolean', value: true, + description: 'Enable injection points') + option('PG_TEST_EXTRA', type: 'string', value: '', description: 'Enable selected extra tests') diff --git a/src/tools/pgindent/typedefs.list b/src/tools/pgindent/typedefs.list index 06b25617bc9..ba7c5f3c75a 100644 --- a/src/tools/pgindent/typedefs.list +++ b/src/tools/pgindent/typedefs.list @@ -1136,6 +1136,7 @@ IdentLine IdentifierLookup IdentifySystemCmd IfStackElem +InjectionPointEntryByName ImportForeignSchemaStmt ImportForeignSchemaType ImportForeignSchema_function -- 2.42.0