0002-Comment-and-documentation-suggestions.patch

From 7a26f1c345e8a8dcf895dcd5d1d45012f46dd826 Mon Sep 17 00:00:00 2001
From: Ashutosh Bapat <ashutosh.bapat@enterprisedb.com>
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:
        <listitem>
         <para>
         Compiles <productname>PostgreSQL</productname> 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 <xref linkend="xfunc-addin-injection-points"/> 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 <xref
+        linkend="xfunc-addin-injection-points"/> for more details.  This option
+        is inteded to be used only by developers for testing.
         </para>
        </listitem>
       </varlistentry>
@@ -3180,12 +3180,12 @@ ninja install
       <listitem>
        <para>
         Compiles <productname>PostgreSQL</productname> 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 <xref linkend="xfunc-addin-injection-points"/> 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 <xref
+        linkend="xfunc-addin-injection-points"/> for more details.  This option
+        is inteded to be used only by developers for testing.
        </para>
       </listitem>
      </varlistentry>
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)
     <title>Injection Points</title>
 
     <para>
-     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 <literal>name</literal> is declared using macro:
 <programlisting>
 INJECTION_POINT(name);
 </programlisting>
+     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.
     </para>
 
     <para>
-     Callbacks can be attached to an injection point by calling:
+     Add-ins can attach callbacks to an already declared injection point by calling:
 <programlisting>
 extern void InjectionPointAttach(const char *name,
                                  const char *library,
                                  const char *function);
 </programlisting>
 
-     <literal>name</literal> is the name of the injection point, that
-     will execute the <literal>function</literal> loaded from
-     <literal>library</literal>.
-     Injection points are saved in a hash table in shared memory, and
-     last until the server is shut down.
+     <literal>name</literal> is the name of the injection point, which when
+     reached during execution will execute the <literal>function</literal>
+     loaded from <literal>library</literal>.
     </para>
 
     <para>
@@ -3547,6 +3544,7 @@ custom_injection_callback(const char *name)
     elog(NOTICE, "%s: executed custom callback", name);
 }
 </programlisting>
+     This callback simply prints a message to server error log with severity NOTCE. But callbacks may implement more complex logic.
     </para>
 
     <para>
@@ -3556,6 +3554,14 @@ extern void InjectionPointDetach(const char *name);
 </programlisting>
     </para>
 
+    <para>
+    A callback attached to an injection point is available across all the
+    backends including the backends started after
+    <literal>InjectionPointAttach</literal> is called. It remains attached till
+    server is running or it is detached using
+    <literal>InjectionPointDetach</literal>.
+    </para>
+
     <para>
      Enabling injections points requires
      <option>--enable-injection-points</option> 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