From 7a26f1c345e8a8dcf895dcd5d1d45012f46dd826 Mon Sep 17 00:00:00 2001 From: Ashutosh Bapat Date: Wed, 17 Jan 2024 16:59:03 +0530 Subject: [PATCH 2/6] Comment and documentation suggestions. ... reflecting a user's point of view. Ashutosh Bapat --- doc/src/sgml/installation.sgml | 24 ++++++++++++------------ doc/src/sgml/xfunc.sgml | 24 +++++++++++++++--------- src/backend/utils/misc/injection_point.c | 11 +++++------ 3 files changed, 32 insertions(+), 27 deletions(-) diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index 51830fc078..f913b6b78f 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -1661,12 +1661,12 @@ 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. + injection points in the server. Injection points allow to run + user-defined code from within the server in pre-defined code paths. + This helps in testing and investigation of concurrency scenarios in a + controlled fashion. This option is disabled by default. See for more details. This option + is inteded to be used only by developers for testing. @@ -3180,12 +3180,12 @@ 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. + injection points in the server. Injection points allow to run + user-defined code from within the server in pre-defined code paths. + This helps in testing and investigation of concurrency scenarios in a + controlled fashion. This option is disabled by default. See for more details. This option + is inteded to be used only by developers for testing. diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index 9dd9eafd22..59dbe73c67 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -3514,27 +3514,24 @@ uint32 WaitEventExtensionNew(const char *wait_event_name) Injection Points - Add-ins can define injection points, that would run user-defined - code when going through a specific code path. This requires the use - of the following macro: + An injection point with a given name name is declared using macro: INJECTION_POINT(name); + There are a few injection points already declared at strategic points within the server code. After adding a new injection point the code needs to be compiled in order for that injection point to be available in the binary. Add-ins written in C-language can declare injection point in their own code using the same macro. - Callbacks can be attached to an injection point by calling: + Add-ins can attach callbacks to an already declared injection point by calling: extern void InjectionPointAttach(const char *name, const char *library, const char *function); - name is the name of the injection point, that - will execute the function loaded from - library. - Injection points are saved in a hash table in shared memory, and - last until the server is shut down. + name is the name of the injection point, which when + reached during execution will execute the function + loaded from library. @@ -3547,6 +3544,7 @@ custom_injection_callback(const char *name) elog(NOTICE, "%s: executed custom callback", name); } + This callback simply prints a message to server error log with severity NOTCE. But callbacks may implement more complex logic. @@ -3556,6 +3554,14 @@ extern void InjectionPointDetach(const char *name); + + A callback attached to an injection point is available across all the + backends including the backends started after + InjectionPointAttach is called. It remains attached till + server is running or it is detached using + InjectionPointDetach. + + Enabling injections points requires with diff --git a/src/backend/utils/misc/injection_point.c b/src/backend/utils/misc/injection_point.c index 205dcfa31d..e9f326a1be 100644 --- a/src/backend/utils/misc/injection_point.c +++ b/src/backend/utils/misc/injection_point.c @@ -3,9 +3,8 @@ * 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, attaching callbacks that would be run in the code - * paths where a named injection point exists. + * Injection points can be used to run arbitrary code by attaching callbacks + * that would be executed in place of the named injection point. * * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group * Portions Copyright (c) 1994, Regents of the University of California @@ -55,7 +54,7 @@ typedef struct InjectionPointEntry #define INJECTION_POINT_HASH_MAX_SIZE 128 /* - * Local cache of injection callbacks already loaded, stored in + * Backend local cache of injection callbacks already loaded, stored in * TopMemoryContext. */ typedef struct InjectionPointCacheEntry @@ -69,7 +68,7 @@ static HTAB *InjectionPointCache = NULL; /* * injection_point_cache_add * - * Add an injection to the local cache. + * Add an injection point to the local cache. */ static void injection_point_cache_add(const char *name, @@ -129,7 +128,7 @@ injection_point_cache_get(const char *name) bool found; InjectionPointCacheEntry *entry; - /* no callback if no cache yet */ + /* No callback if no cache yet. */ if (InjectionPointCache == NULL) return NULL; -- 2.25.1